2006-10-26 Thomas Schwinge <tschwinge@gnu.org>

[task #5956 --- ``Automake'ify GNU Mach's code base'']
	The Automake build system wants us to have these files in the rcs, so
	do that.
	* doc/mach.info: New file, generated.
	* doc/mach.info-1: Likewise.
	* doc/mach.info-2: Likewise.
	* doc/stamp-vti: Likewise.
	* doc/version.texi: Likewise.

4 files changed, 8525 insertions, 0 deletions

diff --git a/doc/mach.info b/doc/mach.info
new file mode 100644
index 00000000..c2100e59
--- /dev/null
+++ b/doc/mach.info
@@ -0,0 +1,175 @@
+This is ../doc/mach.info, produced by makeinfo version 4.8 from
+../doc/mach.texi.
+
+INFO-DIR-SECTION Kernel
+START-INFO-DIR-ENTRY
+* GNUMach: (mach).              Using and programming the GNU Mach microkernel.
+END-INFO-DIR-ENTRY
+
+   This file documents the GNU Mach microkernel.
+
+   This is Edition 0.4, last updated 2001-09-01, of `The GNU Mach
+Reference Manual', for Version 1.3.99.
+
+   Copyright (C) 2001 Free Software Foundation, Inc.
+
+   Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being "Free Software Needs Free Documentation" and
+"GNU Lesser General Public License", the Front-Cover texts being (a)
+(see below), and with the Back-Cover Texts being (b) (see below).  A
+copy of the license is included in the section entitled "GNU Free
+Documentation License".
+
+   (a) The FSF's Front-Cover Text is:
+
+   A GNU Manual
+
+   (b) The FSF's Back-Cover Text is:
+
+   You have freedom to copy and modify this GNU Manual, like GNU
+software.  Copies published by the Free Software Foundation raise
+funds for GNU development.
+
+   This work is based on manual pages under the following copyright and
+license:
+
+Mach Operating System
+Copyright (C) 1991,1990 Carnegie Mellon University
+All Rights Reserved.
+
+   Permission to use, copy, modify and distribute this software and its
+documentation is hereby granted, provided that both the copyright
+notice and this permission notice appear in all copies of the software,
+derivative works or modified versions, and any portions thereof, and
+that both notices appear in supporting documentation.
+
+   CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
+CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR ANY
+DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
+
+
+Indirect:
+mach.info-1: 1914
+mach.info-2: 296589
+
+Tag Table:
+(Indirect)
+Node: Top1914
+Node: Introduction10176
+Node: Audience11007
+Node: Features12042
+Node: Overview13869
+Node: History15062
+Node: Installing15207
+Node: Binary Distributions16431
+Node: Compilation17240
+Node: Configuration18219
+Node: Cross-Compilation31019
+Node: Bootstrap31800
+Ref: Bootstrap-Footnote-132243
+Node: Bootloader32480
+Ref: Bootloader-Footnote-133781
+Node: Modules33863
+Node: Inter Process Communication34668
+Node: Major Concepts35291
+Node: Messaging Interface39096
+Node: Mach Message Call39826
+Node: Message Format43141
+Node: Exchanging Port Rights53602
+Ref: Exchanging Port Rights-Footnote-159168
+Node: Memory59341
+Ref: Memory-Footnote-162435
+Node: Message Send62777
+Ref: Message Send-Footnote-169803
+Node: Message Receive70085
+Ref: Message Receive-Footnote-178722
+Node: Atomicity79003
+Node: Port Manipulation Interface81776
+Node: Port Creation83252
+Node: Port Destruction88038
+Node: Port Names91181
+Node: Port Rights95419
+Node: Ports and other Tasks99216
+Node: Receive Rights103308
+Node: Port Sets108478
+Node: Request Notifications110881
+Node: Virtual Memory Interface115668
+Node: Memory Allocation116921
+Node: Memory Deallocation119446
+Node: Data Transfer120907
+Node: Memory Attributes124432
+Node: Mapping Memory Objects133844
+Node: Memory Statistics137133
+Node: External Memory Management138693
+Node: Memory Object Server139398
+Node: Memory Object Creation142107
+Node: Memory Object Termination146113
+Node: Memory Objects and Data149051
+Node: Memory Object Locking166200
+Node: Memory Object Attributes172093
+Node: Default Memory Manager177933
+Node: Threads and Tasks183654
+Node: Thread Interface183991
+Node: Thread Creation184992
+Node: Thread Termination186109
+Node: Thread Information186580
+Node: Thread Settings192652
+Node: Thread Execution193886
+Node: Scheduling201180
+Node: Thread Priority201535
+Node: Hand-Off Scheduling204174
+Node: Scheduling Policy209166
+Node: Thread Special Ports210499
+Node: Exceptions212945
+Node: Task Interface213824
+Node: Task Creation214836
+Node: Task Termination216171
+Node: Task Information216773
+Node: Task Execution223289
+Node: Task Special Ports227702
+Node: Syscall Emulation231555
+Node: Profiling232782
+Node: Host Interface236540
+Node: Host Ports237525
+Node: Host Information239598
+Node: Host Time244971
+Node: Host Reboot247630
+Node: Processors and Processor Sets248180
+Node: Processor Set Interface249158
+Node: Processor Set Ports249925
+Node: Processor Set Access250760
+Node: Processor Set Creation253023
+Node: Processor Set Destruction254050
+Node: Tasks and Threads on Sets254971
+Node: Processor Set Priority260145
+Node: Processor Set Policy261435
+Node: Processor Set Info263048
+Node: Processor Interface266851
+Node: Hosted Processors267576
+Node: Processor Control268567
+Node: Processors and Sets270033
+Node: Processor Info271914
+Node: Device Interface274650
+Node: Device Reply Server276265
+Node: Device Open277557
+Node: Device Close279677
+Node: Device Read280256
+Node: Device Write283175
+Node: Device Map285980
+Node: Device Status286876
+Node: Device Filter288049
+Node: Kernel Debugger292885
+Node: Operation293612
+Node: Commands296589
+Node: Variables309812
+Node: Expressions311199
+Node: Copying312548
+Node: Documentation License331757
+Node: Free Documentation License332345
+Node: CMU License352244
+Node: Concept Index353475
+Node: Function and Data Index357317
+
+End Tag Table
diff --git a/doc/mach.info-1 b/doc/mach.info-1
new file mode 100644
index 00000000..a1bb76ce
--- /dev/null
+++ b/doc/mach.info-1
@@ -0,0 +1,6683 @@
+This is ../doc/mach.info, produced by makeinfo version 4.8 from
+../doc/mach.texi.
+
+INFO-DIR-SECTION Kernel
+START-INFO-DIR-ENTRY
+* GNUMach: (mach).              Using and programming the GNU Mach microkernel.
+END-INFO-DIR-ENTRY
+
+   This file documents the GNU Mach microkernel.
+
+   This is Edition 0.4, last updated 2001-09-01, of `The GNU Mach
+Reference Manual', for Version 1.3.99.
+
+   Copyright (C) 2001 Free Software Foundation, Inc.
+
+   Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being "Free Software Needs Free Documentation" and
+"GNU Lesser General Public License", the Front-Cover texts being (a)
+(see below), and with the Back-Cover Texts being (b) (see below).  A
+copy of the license is included in the section entitled "GNU Free
+Documentation License".
+
+   (a) The FSF's Front-Cover Text is:
+
+   A GNU Manual
+
+   (b) The FSF's Back-Cover Text is:
+
+   You have freedom to copy and modify this GNU Manual, like GNU
+software.  Copies published by the Free Software Foundation raise
+funds for GNU development.
+
+   This work is based on manual pages under the following copyright and
+license:
+
+Mach Operating System
+Copyright (C) 1991,1990 Carnegie Mellon University
+All Rights Reserved.
+
+   Permission to use, copy, modify and distribute this software and its
+documentation is hereby granted, provided that both the copyright
+notice and this permission notice appear in all copies of the software,
+derivative works or modified versions, and any portions thereof, and
+that both notices appear in supporting documentation.
+
+   CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
+CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR ANY
+DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
+
+
+File: mach.info,  Node: Top,  Next: Introduction,  Up: (dir)
+
+Main Menu
+*********
+
+This is Edition 0.4, last updated 2001-09-01, of `The GNU Mach
+Reference Manual', for Version 1.3.99 of the GNU Mach microkernel.
+
+* Menu:
+
+* Introduction::                  How to use this manual.
+* Installing::                    Setting up GNU Mach on your computer.
+* Bootstrap::                     Running GNU Mach on your machine.
+* Inter Process Communication::   Communication between process.
+* Virtual Memory Interface::      Allocating and deallocating virtual memory.
+* External Memory Management::    Handling memory pages in user space.
+* Threads and Tasks::             Handling of threads and tasks.
+* Host Interface::                Interface to a Mach host.
+* Processors and Processor Sets:: Handling processors and sets of processors.
+* Device Interface::              Accesing kernel devices.
+* Kernel Debugger::               How to use the built-in kernel debugger.
+
+Appendices
+
+* Copying::                       The GNU General Public License says how you
+                                  can copy and share the GNU Mach microkernel.
+* Documentation License::         This manual is under the GNU Free
+                                  Documentation License.
+
+Indices
+
+* Concept Index::                 Index of concepts and programs.
+* Function and Data Index::       Index of functions, variables and data types.
+
+
+ --- The Detailed Node Listing ---
+
+Introduction
+
+* Audience::                      The people for whom this manual is written.
+* Features::                      Reasons to install and use GNU Mach.
+* Overview::                      Basic architecture of the Mach microkernel.
+* History::                       The story about Mach.
+
+Installing
+
+* Binary Distributions::          Obtaining ready-to-run GNU distributions.
+* Compilation::                   Building GNU Mach from its source code.
+* Configuration::                 Configuration options at compilation time.
+* Cross-Compilation::             Building GNU Mach from another system.
+
+Bootstrap
+
+* Bootloader::                    Starting the microkernel, or other OSes.
+* Modules::                       Starting the first task of the OS.
+
+Inter Process Communication
+
+* Major Concepts::                The concepts behind the Mach IPC system.
+* Messaging Interface::           Composing, sending and receiving messages.
+* Port Manipulation Interface::   Manipulating ports, port rights, port sets.
+
+Messaging Interface
+
+* Mach Message Call::             Sending and receiving messages.
+* Message Format::                The format of Mach messages.
+* Exchanging Port Rights::        Sending and receiving port rights.
+* Memory::                        Passing memory regions in messages.
+* Message Send::                  Sending messages.
+* Message Receive::               Receiving messages.
+* Atomicity::                     Atomicity of port rights.
+
+Port Manipulation Interface
+
+* Port Creation::                 How to create new ports and port sets.
+* Port Destruction::              How to destroy ports and port sets.
+* Port Names::                    How to query and manipulate port names.
+* Port Rights::                   How to work with port rights.
+* Ports and other Tasks::         How to move rights between tasks.
+* Receive Rights::                How to work with receive rights.
+* Port Sets::                     How to work with port sets.
+* Request Notifications::         How to request notifications for events.
+
+Virtual Memory Interface
+
+* Memory Allocation::             Allocation of new virtual memory.
+* Memory Deallocation::           Freeing unused virtual memory.
+* Data Transfer::                 Reading, writing and copying memory.
+* Memory Attributes::             Tweaking memory regions.
+* Mapping Memory Objects::        How to map memory objects.
+* Memory Statistics::             How to get statistics about memory usage.
+
+External Memory Management
+
+* Memory Object Server::          The basics of external memory management.
+* Memory Object Creation::        How new memory objects are created.
+* Memory Object Termination::     How memory objects are terminated.
+* Memory Objects and Data::       Data transfer to and from memory objects.
+* Memory Object Locking::         How memory objects are locked.
+* Memory Object Attributes::      Manipulating attributes of memory objects.
+* Default Memory Manager::        Setting and using the default memory manager.
+
+Threads and Tasks
+
+* Thread Interface::              Manipulating threads.
+* Task Interface::                Manipulating tasks.
+* Profiling::                     Profiling threads and tasks.
+
+Thread Interface
+
+* Thread Creation::               Creating threads.
+* Thread Termination::            Terminating threads.
+* Thread Information::            How to get informations on threads.
+* Thread Settings::               How to set threads related informations.
+* Thread Execution::              How to control the thread's machine state.
+* Scheduling::                    Operations on thread scheduling.
+* Thread Special Ports::          How to handle the thread's special ports.
+* Exceptions::                    Managing exceptions.
+
+Scheduling
+
+* Thread Priority::               Changing the priority of a thread.
+* Hand-Off Scheduling::           Switch to a new thread.
+* Scheduling Policy::             Setting the scheduling policy.
+
+Task Interface
+
+* Task Creation::                 Creating tasks.
+* Task Termination::              Terminating tasks.
+* Task Information::              Informations on tasks.
+* Task Execution::                Thread scheduling in a task.
+* Task Special Ports::            How to get and set the task's special ports.
+* Syscall Emulation::             How to emulate system calls.
+
+Host Interface
+
+* Host Ports::                    Ports representing a host.
+* Host Information::              Query information about a host.
+* Host Time::                     Functions to query manipulate the host time.
+* Host Reboot::                   Rebooting the system.
+
+Processors and Processor Sets
+
+* Processor Set Interface::       How to work with processor sets.
+* Processor Interface::           How to work with individual processors.
+
+Processor Set Interface
+
+* Processor Set Ports::           Ports representing a processor set.
+* Processor Set Access::          How the processor sets are accessed.
+* Processor Set Creation::        How new processor sets are created.
+* Processor Set Destruction::     How processor sets are destroyed.
+* Tasks and Threads on Sets::     Assigning tasks or threads to processor sets.
+* Processor Set Priority::        Specifying the priority of a processor set.
+* Processor Set Policy::          Changing the processor set policies.
+* Processor Set Info::            Obtaining information about a processor set.
+
+Processor Interface
+
+* Hosted Processors::             Getting a list of all processors on a host.
+* Processor Control::             Starting, stopping, controlling processors.
+* Processors and Sets::           Combining processors into processor sets.
+* Processor Info::                Obtaining information on processors.
+
+Device Interface
+
+* Device Open::                   Opening hardware devices.
+* Device Close::                  Closing hardware devices.
+* Device Read::                   Reading data from the device.
+* Device Write::                  Writing data to the device.
+* Device Map::                    Mapping devices into virtual memory.
+* Device Status::                 Querying and manipulating a device.
+* Device Filter::                 Filtering packets arriving on a device.
+
+Kernel Debugger
+
+* Operation::                     Basic architecture of the kernel debugger.
+* Commands::                      Available commands in the kernel debugger.
+* Variables::                     Access of variables from the kernel debugger.
+* Expressions::                   Usage of expressions in the kernel debugger.
+
+Documentation License
+
+* Free Documentation License::    The GNU Free Documentation License.
+* CMU License::                   The CMU license applies to the original Mach
+                                  kernel and its documentation.
+
+
+File: mach.info,  Node: Introduction,  Next: Installing,  Prev: Top,  Up: Top
+
+1 Introduction
+**************
+
+GNU Mach is the microkernel of the GNU Project.  It is the base of the
+operating system, and provides its functionality to the Hurd servers,
+the GNU C Library and all user applications.  The microkernel itself
+does not provide much functionality of the system, just enough to make
+it possible for the Hurd servers and the C library to implement the
+missing features you would expect from a POSIX compatible operating
+system.
+
+* Menu:
+
+* Audience::                      The people for whom this manual is written.
+* Features::                      Reasons to install and use GNU Mach.
+* Overview::                      Basic architecture of the Mach microkernel.
+* History::                       The story about Mach.
+
+
+File: mach.info,  Node: Audience,  Next: Features,  Up: Introduction
+
+1.1 Audience
+============
+
+This manual is designed to be useful to everybody who is interested in
+using, administering, or programming the Mach microkernel.
+
+   If you are an end-user and you are looking for help on running the
+Mach kernel, the first few chapters of this manual describe the
+essential parts of installing and using the kernel in the GNU operating
+system.
+
+   The rest of this manual is a technical discussion of the Mach
+programming interface and its implementation, and would not be helpful
+until you want to learn how to extend the system or modify the kernel.
+
+   This manual is organized according to the subsystems of Mach, and
+each chapter begins with descriptions of conceptual ideas that are
+related to that subsystem.  If you are a programmer and want to learn
+more about, say, the Mach IPC subsystem, you can skip to the IPC chapter
+(*note Inter Process Communication::), and read about the related
+concepts and interface definitions.
+
+
+File: mach.info,  Node: Features,  Next: Overview,  Prev: Audience,  Up: Introduction
+
+1.2 Features
+============
+
+GNU Mach is not the most advanced microkernel known to the planet, nor
+is it the fastest or smallest, but it has a rich set of interfaces and
+some features which make it useful as the base of the Hurd system.
+
+it's free software
+     Anybody can use, modify, and redistribute it under the terms of
+     the GNU General Public License (*note Copying::).  GNU Mach is
+     part of the GNU system, which is a complete operating system
+     licensed under the GPL.
+
+it's built to survive
+     As a microkernel, GNU Mach doesn't implement a lot of the features
+     commonly found in an operating system, but only the bare minimum
+     that is required to implement a full operating system on top of it.
+     This means that a lot of the operating system code is maintained
+     outside of GNU Mach, and while this code may go through a complete
+     redesign, the code of the microkernel can remain comparatively
+     stable.
+
+it's scalable
+     Mach is particularly well suited for SMP and network cluster
+     techniques.  Thread support is provided at the kernel level, and
+     the kernel itself takes advantage of that.  Network transparency
+     at the IPC level makes resources of the system available across
+     machine boundaries (with NORMA IPC, currently not available in GNU
+     Mach).
+
+it exists
+     The Mach microkernel is real software that works Right Now.  It is
+     not a research or a proposal.  You don't have to wait at all
+     before you can start using and developing it.  Mach has been used
+     in many operating systems in the past, usually as the base for a
+     single UNIX server.  In the GNU system, Mach is the base of a
+     functional multi-server operating system, the Hurd.
+
+
+File: mach.info,  Node: Overview,  Next: History,  Prev: Features,  Up: Introduction
+
+1.3 Overview
+============
+
+An operating system kernel provides a framework for programs to share a
+computer's hardware resources securely and efficiently.  This requires
+that the programs are seperated and protected from each other.  To make
+running multiple programs in parallel useful, there also needs to be a
+facility for programs to exchange information by communication.
+
+   The Mach microkernel provides abstractions of the underlying hardware
+resources like devices and memory.  It organizes the running programs
+into tasks and threads (points of execution in the tasks).  In addition,
+Mach provides a rich interface for inter-process communication.
+
+   What Mach does not provide is a POSIX compatible programming
+interface.  In fact, it has no understanding of file systems, POSIX
+process semantics, network protocols and many more.  All this is
+implemented in tasks running on top of the microkernel.  In the GNU
+operating system, the Hurd servers and the C library share the
+responsibility to implement the POSIX interface, and the additional
+interfaces which are specific to the GNU system.
+
+
+File: mach.info,  Node: History,  Prev: Overview,  Up: Introduction
+
+1.4 History
+===========
+
+XXX A few lines about the history of Mach here.
+
+
+File: mach.info,  Node: Installing,  Next: Bootstrap,  Prev: Introduction,  Up: Top
+
+2 Installing
+************
+
+Before you can use the Mach microkernel in your system you'll need to
+install it and all components you want to use with it, e.g. the rest of
+the operating system.  You also need a bootloader to load the kernel
+from the storage medium and run it when the computer is started.
+
+   GNU Mach is only available for Intel i386-compatible architectures
+(such as the Pentium) currently.  If you have a different architecture
+and want to run the GNU Mach microkernel, you will need to port the
+kernel and all other software of the system to your machine's
+architecture.  Porting is an involved process which requires
+considerable programming skills, and it is not recommended for the
+faint-of-heart.  If you have the talent and desire to do a port, contact
+<bug-hurd@gnu.org> in order to coordinate the effort.
+
+* Menu:
+
+* Binary Distributions::          Obtaining ready-to-run GNU distributions.
+* Compilation::                   Building GNU Mach from its source code.
+* Configuration::                 Configuration options at compile time.
+* Cross-Compilation::             Building GNU Mach from another system.
+
+
+File: mach.info,  Node: Binary Distributions,  Next: Compilation,  Up: Installing
+
+2.1 Binary Distributions
+========================
+
+By far the easiest and best way to install GNU Mach and the operating
+system is to obtain a GNU binary distribution.  The GNU operating
+system consists of GNU Mach, the Hurd, the C library and many
+applications.  Without the GNU operating system, you will only have a
+microkernel, which is not very useful by itself, without the other
+programs.
+
+   Building the whole operating system takes a huge effort, and you are
+well advised to not do it yourself, but to get a binary distribution of
+the GNU operating system.  The distribution also includes a binary of
+the GNU Mach microkernel.
+
+   Information on how to obtain the GNU system can be found in the Hurd
+info manual.
+
+
+File: mach.info,  Node: Compilation,  Next: Configuration,  Prev: Binary Distributions,  Up: Installing
+
+2.2 Compilation
+===============
+
+If you already have a running GNU system, and only want to recompile
+the kernel, for example to select a different set of included hardware
+drivers, you can easily do this.  You need the GNU C compiler and MiG,
+the Mach interface generator, which both come in their own packages.
+
+   Building and installing the kernel is as easy as with any other GNU
+software package.  The configure script is used to configure the source
+and set the compile time options.  The compilation is done by running:
+
+     make
+
+   To install the kernel and its header files, just enter the command:
+
+     make install
+
+   This will install the kernel into $(prefix)/boot/gnumach and the
+header files into $(prefix)/include.  You can also only install the
+kernel or the header files.  For this, the two targets install-kernel
+and install-headers are provided.
+
+
+File: mach.info,  Node: Configuration,  Next: Cross-Compilation,  Prev: Compilation,  Up: Installing
+
+2.3 Configuration
+=================
+
+The following options can be passed to the configure script as command
+line arguments and control what components are built into the kernel, or
+where it is installed.
+
+   The default for an option is to be disabled, unless otherwise noted.
+
+   This table is out-dated.  Please see the file `i386/README-Drivers'
+and the output of `[GNU Mach]/configure --help=recursive'.
+
+`--prefix PREFIX'
+     Sets the prefix to PREFIX.  The default prefix is the empty
+     string, which is the correct value for the GNU system.  The prefix
+     is prepended to all file names at installation time.
+
+`--enable-kdb'
+     Enables the in-kernel debugger.  This is only useful if you
+     actually anticipate debugging the kernel.  It is not enabled by
+     default because it adds considerably to the unpageable memory
+     footprint of the kernel.  *Note Kernel Debugger::.
+
+`--enable-kmsg'
+     Enables the kernel message device kmsg.
+
+`--enable-lpr'
+     Enables the parallel port devices lpr%d.
+
+`--enable-floppy'
+     Enables the PC floppy disk controller devices fd%d.
+
+`--enable-ide'
+     Enables the IDE controller devices hd%d, hd%ds%d.
+
+   The following options enable drivers for various SCSI controller.
+SCSI devices are named sd%d (disks) or cd%d (CD ROMs).
+
+`--enable-advansys'
+     Enables the AdvanSys SCSI controller devices sd%d, cd%d.
+
+`--enable-buslogic'
+     Enables the BusLogic SCSI controller devices sd%d, cd%d.
+
+`--disable-flashpoint'
+     Only meaningful in conjunction with `--enable-buslogic'.  Omits the
+     FlshPoint support.  This option is enabled by default if
+     `--enable-buslogic' is specified.
+
+`--enable-u1434f'
+     Enables the UltraStor 14F/34F SCSI controller devices sd%d, cd%d.
+
+`--enable-ultrastor'
+     Enables the UltraStor SCSI controller devices sd%d, cd%d.
+
+`--enable-aha152x'
+`--enable-aha2825'
+     Enables the Adaptec AHA-152x/2825 SCSI controller devices sd%d,
+     cd%d.
+
+`--enable-aha1542'
+     Enables the Adaptec AHA-1542 SCSI controller devices sd%d, cd%d.
+
+`--enable-aha1740'
+     Enables the Adaptec AHA-1740 SCSI controller devices sd%d, cd%d.
+
+`--enable-aic7xxx'
+     Enables the Adaptec AIC7xxx SCSI controller devices sd%d, cd%d.
+
+`--enable-futuredomain'
+     Enables the Future Domain 16xx SCSI controller devices sd%d, cd%d.
+
+`--enable-in2000'
+     Enables the Always IN 2000 SCSI controller devices sd%d, cd%d.
+
+`--enable-ncr5380'
+`--enable-ncr53c400'
+     Enables the generic NCR5380/53c400 SCSI controller devices sd%d,
+     cd%d.
+
+`--enable-ncr53c406a'
+     Enables the NCR53c406a SCSI controller devices sd%d, cd%d.
+
+`--enable-pas16'
+     Enables the PAS16 SCSI controller devices sd%d, cd%d.
+
+`--enable-seagate'
+     Enables the Seagate ST02 and Future Domain TMC-8xx SCSI controller
+     devices sd%d, cd%d.
+
+`--enable-t128'
+`--enable-t128f'
+`--enable-t228'
+     Enables the Trantor T128/T128F/T228 SCSI controller devices sd%d,
+     cd%d.
+
+`--enable-ncr53c7xx'
+     Enables the NCR53C7,8xx SCSI controller devices sd%d, cd%d.
+
+`--enable-eatadma'
+     Enables the EATA-DMA (DPT, NEC, AT&T, SNI, AST, Olivetti,
+     Alphatronix) SCSI controller devices sd%d, cd%d.
+
+`--enable-eatapio'
+     Enables the EATA-PIO (old DPT PM2001, PM2012A) SCSI controller
+     devices sd%d, cd%d.
+
+`--enable-wd7000'
+     Enables the WD 7000 SCSI controller devices sd%d, cd%d.
+
+`--enable-eata'
+     Enables the EATA ISA/EISA/PCI (DPT and generic EATA/DMA-compliant
+     boards) SCSI controller devices sd%d, cd%d.
+
+`--enable-am53c974'
+`--enable-am79c974'
+     Enables the AM53/79C974 SCSI controller devices sd%d, cd%d.
+
+`--enable-dtc3280'
+`--enable-dtc3180'
+     Enables the DTC3180/3280 SCSI controller devices sd%d, cd%d.
+
+`--enable-ncr53c8xx'
+`--enable-dc390w'
+`--enable-dc390u'
+`--enable-dc390f'
+     Enables the NCR53C8XX SCSI controller devices sd%d, cd%d.
+
+`--enable-dc390t'
+`--enable-dc390'
+     Enables the Tekram DC-390(T) SCSI controller devices sd%d, cd%d.
+
+`--enable-ppa'
+     Enables the IOMEGA Parallel Port ZIP drive device sd%d.
+
+`--enable-qlogicfas'
+     Enables the Qlogic FAS SCSI controller devices sd%d, cd%d.
+
+`--enable-qlogicisp'
+     Enables the Qlogic ISP SCSI controller devices sd%d, cd%d.
+
+`--enable-gdth'
+     Enables the GDT SCSI Disk Array controller devices sd%d, cd%d.
+
+   The following options enable drivers for various ethernet cards.
+NIC device names are usually eth%d, except for the pocket adaptors.
+
+   GNU Mach does only autodetect one ethernet card.  To enable any
+further cards, the source code has to be edited.
+
+`--enable-ne2000'
+`--enable-ne1000'
+     Enables the NE2000/NE1000 ISA netword card devices eth%d.
+
+`--enable-3c503'
+`--enable-el2'
+     Enables the 3Com 503 (Etherlink II) netword card devices eth%d.
+
+`--enable-3c509'
+`--enable-3c579'
+`--enable-el3'
+     Enables the 3Com 509/579 (Etherlink III) netword card devices
+     eth%d.
+
+`--enable-wd80x3'
+     Enables the WD80X3 netword card devices eth%d.
+
+`--enable-3c501'
+`--enable-el1'
+     Enables the 3COM 501 netword card devices eth%d.
+
+`--enable-ul'
+     Enables the SMC Ultra netword card devices eth%d.
+
+`--enable-ul32'
+     Enables the SMC Ultra 32 netword card devices eth%d.
+
+`--enable-hplanplus'
+     Enables the HP PCLAN+ (27247B and 27252A) netword card devices
+     eth%d.
+
+`--enable-hplan'
+     Enables the HP PCLAN (27245 and other 27xxx series) netword card
+     devices eth%d.
+
+`--enable-3c59x'
+`--enable-3c90x'
+`--enable-vortex'
+     Enables the 3Com 590/900 series (592/595/597/900/905)
+     "Vortex/Boomerang" netword card devices eth%d.
+
+`--enable-seeq8005'
+     Enables the Seeq8005 netword card devices eth%d.
+
+`--enable-hp100'
+`--enable-hpj2577'
+`--enable-hpj2573'
+`--enable-hp27248b'
+`--enable-hp2585'
+     Enables the HP 10/100VG PCLAN (ISA, EISA, PCI) netword card devices
+     eth%d.
+
+`--enable-ac3200'
+     Enables the Ansel Communications EISA 3200 netword card devices
+     eth%d.
+
+`--enable-e2100'
+     Enables the Cabletron E21xx netword card devices eth%d.
+
+`--enable-at1700'
+     Enables the AT1700 (Fujitsu 86965) netword card devices eth%d.
+
+`--enable-eth16i'
+`--enable-eth32'
+     Enables the ICL EtherTeam 16i/32 netword card devices eth%d.
+
+`--enable-znet'
+`--enable-znote'
+     Enables the Zenith Z-Note netword card devices eth%d.
+
+`--enable-eexpress'
+     Enables the EtherExpress 16 netword card devices eth%d.
+
+`--enable-eexpresspro'
+     Enables the EtherExpressPro netword card devices eth%d.
+
+`--enable-eexpresspro100'
+     Enables the Intel EtherExpressPro PCI 10+/100B/100+ netword card
+     devices eth%d.
+
+`--enable-depca'
+`--enable-de100'
+`--enable-de101'
+`--enable-de200'
+`--enable-de201'
+`--enable-de202'
+`--enable-de210'
+`--enable-de422'
+     Enables the DEPCA, DE10x, DE200, DE201, DE202, DE210, DE422
+     netword card devices eth%d.
+
+`--enable-ewrk3'
+`--enable-de203'
+`--enable-de204'
+`--enable-de205'
+     Enables the EtherWORKS 3 (DE203, DE204, DE205) netword card devices
+     eth%d.
+
+`--enable-de4x5'
+`--enable-de425'
+`--enable-de434'
+`--enable-435'
+`--enable-de450'
+`--enable-500'
+     Enables the DE425, DE434, DE435, DE450, DE500 netword card devices
+     eth%d.
+
+`--enable-apricot'
+     Enables the Apricot XEN-II on board ethernet netword card devices
+     eth%d.
+
+`--enable-wavelan'
+     Enables the AT&T WaveLAN & DEC RoamAbout DS netword card devices
+     eth%d.
+
+`--enable-3c507'
+`--enable-el16'
+     Enables the 3Com 507 netword card devices eth%d.
+
+`--enable-3c505'
+`--enable-elplus'
+     Enables the 3Com 505 netword card devices eth%d.
+
+`--enable-de600'
+     Enables the D-Link DE-600 netword card devices eth%d.
+
+`--enable-de620'
+     Enables the D-Link DE-620 netword card devices eth%d.
+
+`--enable-skg16'
+     Enables the Schneider & Koch G16 netword card devices eth%d.
+
+`--enable-ni52'
+     Enables the NI5210 netword card devices eth%d.
+
+`--enable-ni65'
+     Enables the NI6510 netword card devices eth%d.
+
+`--enable-atp'
+     Enables the AT-LAN-TEC/RealTek pocket adaptor netword card devices
+     atp%d.
+
+`--enable-lance'
+`--enable-at1500'
+`--enable-ne2100'
+     Enables the AMD LANCE and PCnet (AT1500 and NE2100) netword card
+     devices eth%d.
+
+`--enable-elcp'
+`--enable-tulip'
+     Enables the DECchip Tulip (dc21x4x) PCI netword card devices eth%d.
+
+`--enable-fmv18x'
+     Enables the FMV-181/182/183/184 netword card devices eth%d.
+
+`--enable-3c515'
+     Enables the 3Com 515 ISA Fast EtherLink netword card devices eth%d.
+
+`--enable-pcnet32'
+     Enables the AMD PCI PCnet32 (PCI bus NE2100 cards) netword card
+     devices eth%d.
+
+`--enable-ne2kpci'
+     Enables the PCI NE2000 netword card devices eth%d.
+
+`--enable-yellowfin'
+     Enables the Packet Engines Yellowfin Gigabit-NIC netword card
+     devices eth%d.
+
+`--enable-rtl8139'
+`--enable-rtl8129'
+     Enables the RealTek 8129/8139 (not 8019/8029!)  netword card
+     devices eth%d.
+
+`--enable-epic'
+`--enable-epic100'
+     Enables the SMC 83c170/175 EPIC/100 (EtherPower II) netword card
+     devices eth%d.
+
+`--enable-tlan'
+     Enables the TI ThunderLAN netword card devices eth%d.
+
+`--enable-viarhine'
+     Enables the VIA Rhine netword card devices eth%d.
+
+`--enable-hamachi'
+     Enables the Packet Engines "Hamachi" GNIC-2 Gigabit Ethernet
+     devices eth%d.
+
+`--enable-intel-gige'
+     Enables the Intel PCI Gigabit Ethernet devices eth%d.
+
+`--enable-myson803'
+     Enables the Myson MTD803 Ethernet adapter series devices eth%d.
+
+`--enable-natsemi'
+     Enables the National Semiconductor DP8381x series PCI Ethernet
+     devices eth%d.
+
+`--enable-ns820'
+     Enables the National Semiconductor DP8382x series PCI Ethernet
+     devices eth%d.
+
+`--enable-starfire'
+     Enables the Adaptec Starfire network adapter devices eth%d.
+
+`--enable-sundance'
+     Enables the Sundance ST201 "Alta" PCI Ethernet devices eth%d.
+
+`--enable-winbond-840'
+     Enables the Winbond W89c840 PCI Ethernet devices eth%d.
+
+   The following options either enable drivers for supported PCMCIA
+bridges or control the overall behaviour of the GNU Mach PCMCIA core.
+To make use of GNU Mach PCMCIA support you need to have the
+corresponding userland applications (GNU Mach Card Services) installed.
+
+`--enable-i82365'
+     Enables the driver for the Intel 82365 and compatible PC Card
+     controllers, and Yenta-compatible PCI-to-CardBus controllers.
+
+`--enable-pcmcia-isa'
+     Enables ISA-bus related bits in the GNU Mach PCMCIA core.  This is
+     generally a good idea, since it does not only have effect if your
+     PC Card bridge is attached to the ISA bus, but provides more (ISA)
+     interrupts to the Card Services for it to assign to the cards in
+     turn.
+
+   The following options enable drivers for supported PCMCIA Ethernet
+controllers.  NIC device names are usually eth%d.
+
+`--enable-3c574_cs'
+     Enables the PCMCIA ethernet driver for the 3Com 3c574 "RoadRunner".
+
+`--enable-3c589_cs'
+     Enables the driver for the 3Com 3c589 PCMCIA card.
+
+`--enable-axnet_cs'
+     Enables the driver for the Asix AX88190-based PCMCIA cards.
+
+`--enable-fmvj18x_cs'
+     Enables the driver for PCMCIA cards with the fmvj18x chipset.
+
+`--enable-nmclan_cs'
+     Enables the driver for the New Media Ethernet LAN PCMCIA cards.
+
+`--enable-pcnet_cs'
+     Enables the driver for NS8390-based PCMCIA cards.
+
+     This driver supports the D-Link DE-650 and Linksys EthernetCard
+     cards, the newer D-Link and Linksys combo cards, Accton EN2212
+     cards, the RPTI EP400, and the PreMax PE-200 in non-shared-memory
+     mode, and the IBM Credit Card Adapter, the NE4100, the Thomas
+     Conrad ethernet card, and the Kingston KNE-PCM/x in shared-memory
+     mode.  It will also handle the Socket EA card in either mode.
+
+`--enable-smc91c92_cs'
+     Enables the driver for SMC91c92-based PCMCIA cards.
+
+`--enable-xirc2ps_cs'
+     Enables the driver for Xircom CreditCard and Realport PCMCIA
+     ethernet adapters.
+
+   The following options enable drivers for supported PCMCIA Wireless
+LAN network controllers.  NIC device names are usually eth%d.
+
+   Please mind, that you need to have some userland applications (the
+GNU Mach Wireless Tools) installed, in order to make use of these
+devices.
+
+`--enable-orinoco_cs'
+     Enables the driver for the Hermes or Prism 2 chipset based PCMCIA
+     wireless adapters, with Lucent/Agere, Intersil or Symbol firmware.
+
+     This driver is suitable for PCMCIA wireless adapters, such as the
+     Lucent WavelanIEEE/Orinoco cards and their OEM (Cabletron/EnteraSys
+     RoamAbout 802.11, ELSA Airlancer, Melco Buffalo and others).  It
+     should also be usable on various Prism II based cards such as the
+     Linksys, D-Link and Farallon Skyline. It should also work on Symbol
+     cards such as the 3Com AirConnect and Ericsson WLAN.
+
+
+File: mach.info,  Node: Cross-Compilation,  Prev: Configuration,  Up: Installing
+
+2.4 Cross-Compilation
+=====================
+
+Another way to install the kernel is to use an existing operating system
+in order to compile the kernel binary.  This is called
+"cross-compiling", because it is done between two different platforms.
+If the pre-built kernels are not working for you, and you can't ask
+someone to compile a custom kernel for your machine, this is your last
+chance to get a kernel that boots on your hardware.
+
+   Luckily, the kernel does have light dependencies.  You don't even
+need a cross compiler if your build machine has a compiler and is the
+same architecture as the system you want to run GNU Mach on.
+
+   You need a cross-mig, though.
+
+   XXX More info needed.
+
+
+File: mach.info,  Node: Bootstrap,  Next: Inter Process Communication,  Prev: Installing,  Up: Top
+
+3 Bootstrap
+***********
+
+Bootstrapping(1) is the procedure by which your machine loads the
+microkernel and transfers control to the operating system.
+
+* Menu:
+
+* Bootloader::                    Starting the microkernel, or other OSes.
+* Modules::                       Starting the first task of the OS.
+
+   ---------- Footnotes ----------
+
+   (1) The term "bootstrapping" refers to a Dutch legend about a boy
+who was able to fly by pulling himself up by his bootstraps.  In
+computers, this term refers to any process where a simple system
+activates a more complicated system.
+
+
+File: mach.info,  Node: Bootloader,  Next: Modules,  Up: Bootstrap
+
+3.1 Bootloader
+==============
+
+The "bootloader" is the first software that runs on your machine.  Many
+hardware architectures have a very simple startup routine which reads a
+very simple bootloader from the beginning of the internal hard disk,
+then transfers control to it.  Other architectures have startup
+routines which are able to understand more of the contents of the hard
+disk, and directly start a more advanced bootloader.
+
+   Currently, "GRUB"(1) is the preferred GNU bootloader.  GRUB provides
+advanced functionality, and is capable of loading several different
+kernels (such as Mach, Linux, DOS, and the *BSD family).  *Note
+Introduction: (grub)Top.
+
+   GNU Mach conforms to the Multiboot specification which defines an
+interface between the bootloader and the components that run very early
+at startup.  GNU Mach can be started by any bootloader which supports
+the multiboot standard.  After the bootloader loaded the kernel image to
+a designated address in the system memory, it jumps into the startup
+code of the kernel.  This code initializes the kernel and detects the
+available hardware devices.  Afterwards, the first system task is
+started.  *Note Overview: (multiboot)Top.
+
+   ---------- Footnotes ----------
+
+   (1) The GRand Unified Bootloader, available from
+`http://www.uruk.org/grub/'.
+
+
+File: mach.info,  Node: Modules,  Prev: Bootloader,  Up: Bootstrap
+
+3.2 Modules
+===========
+
+Because the microkernel does not provide filesystem support and other
+features necessary to load the first system task from a storage medium,
+the first task is loaded by the bootloader as a module to a specified
+address.  In the GNU system, this first program is the `serverboot'
+executable.  GNU Mach inserts the host control port and the device
+master port into this task and appends the port numbers to the command
+line before executing it.
+
+   The `serverboot' program is responsible for loading and executing
+the rest of the Hurd servers.  Rather than containing specific
+instructions for starting the Hurd, it follows general steps given in a
+user-supplied boot script.
+
+   XXX More about boot scripts.
+
+
+File: mach.info,  Node: Inter Process Communication,  Next: Virtual Memory Interface,  Prev: Bootstrap,  Up: Top
+
+4 Inter Process Communication
+*****************************
+
+This chapter describes the details of the Mach IPC system.  First the
+actual calls concerned with sending and receiving messages are
+discussed, then the details of the port system are described in detail.
+
+* Menu:
+
+* Major Concepts::                The concepts behind the Mach IPC system.
+* Messaging Interface::           Composing, sending and receiving messages.
+* Port Manipulation Interface::   Manipulating ports, port rights, port sets.
+
+
+File: mach.info,  Node: Major Concepts,  Next: Messaging Interface,  Up: Inter Process Communication
+
+4.1 Major Concepts
+==================
+
+The Mach kernel provides message-oriented, capability-based interprocess
+communication.  The interprocess communication (IPC) primitives
+efficiently support many different styles of interaction, including
+remote procedure calls (RPC), object-oriented distributed programming,
+streaming of data, and sending very large amounts of data.
+
+   The IPC primitives operate on three abstractions: messages, ports,
+and port sets.  User tasks access all other kernel services and
+abstractions via the IPC primitives.
+
+   The message primitives let tasks send and receive messages.  Tasks
+send messages to ports.  Messages sent to a port are delivered reliably
+(messages may not be lost) and are received in the order in which they
+were sent.  Messages contain a fixed-size header and a variable amount
+of typed data following the header.  The header describes the
+destination and size of the message.
+
+   The IPC implementation makes use of the VM system to efficiently
+transfer large amounts of data.  The message body can contain the
+address of a region in the sender's address space which should be
+transferred as part of the message.  When a task receives a message
+containing an out-of-line region of data, the data appears in an unused
+portion of the receiver's address space.  This transmission of
+out-of-line data is optimized so that sender and receiver share the
+physical pages of data copy-on-write, and no actual data copy occurs
+unless the pages are written.  Regions of memory up to the size of a
+full address space may be sent in this manner.
+
+   Ports hold a queue of messages.  Tasks operate on a port to send and
+receive messages by exercising capabilities for the port.  Multiple
+tasks can hold send capabilities, or rights, for a port.  Tasks can also
+hold send-once rights, which grant the ability to send a single message.
+Only one task can hold the receive capability, or receive right, for a
+port.  Port rights can be transferred between tasks via messages.  The
+sender of a message can specify in the message body that the message
+contains a port right.  If a message contains a receive right for a
+port, then the receive right is removed from the sender of the message
+and the right is transferred to the receiver of the message.  While the
+receive right is in transit, tasks holding send rights can still send
+messages to the port, and they are queued until a task acquires the
+receive right and uses it to receive the messages.
+
+   Tasks can receive messages from ports and port sets.  The port set
+abstraction allows a single thread to wait for a message from any of
+several ports.  Tasks manipulate port sets with a capability, or
+port-set right, which is taken from the same space as the port
+capabilities.  The port-set right may not be transferred in a message.
+A port set holds receive rights, and a receive operation on a port set
+blocks waiting for a message sent to any of the constituent ports.  A
+port may not belong to more than one port set, and if a port is a member
+of a port set, the holder of the receive right can't receive directly
+from the port.
+
+   Port rights are a secure, location-independent way of naming ports.
+The port queue is a protected data structure, only accessible via the
+kernel's exported message primitives.  Rights are also protected by the
+kernel; there is no way for a malicious user task to guess a port name
+and send a message to a port to which it shouldn't have access.  Port
+rights do not carry any location information.  When a receive right for
+a port moves from task to task, and even between tasks on different
+machines, the send rights for the port remain unchanged and continue to
+function.
+
+
+File: mach.info,  Node: Messaging Interface,  Next: Port Manipulation Interface,  Prev: Major Concepts,  Up: Inter Process Communication
+
+4.2 Messaging Interface
+=======================
+
+This section describes how messages are composed, sent and received
+within the Mach IPC system.
+
+* Menu:
+
+* Mach Message Call::             Sending and receiving messages.
+* Message Format::                The format of Mach messages.
+* Exchanging Port Rights::        Sending and receiving port rights.
+* Memory::                        Passing memory regions in messages.
+* Message Send::                  Sending messages.
+* Message Receive::               Receiving messages.
+* Atomicity::                     Atomicity of port rights.
+
+
+File: mach.info,  Node: Mach Message Call,  Next: Message Format,  Up: Messaging Interface
+
+4.2.1 Mach Message Call
+-----------------------
+
+To use the `mach_msg' call, you can include the header files
+`mach/port.h' and `mach/message.h'.
+
+ -- Function: mach_msg_return_t mach_msg (mach_msg_header_t *MSG,
+          mach_msg_option_t OPTION, mach_msg_size_t SEND_SIZE,
+          mach_msg_size_t RCV_SIZE, mach_port_t RCV_NAME,
+          mach_msg_timeout_t TIMEOUT, mach_port_t NOTIFY)
+     The `mach_msg' function is used to send and receive messages.  Mach
+     messages contain typed data, which can include port rights and
+     references to large regions of memory.
+
+     MSG is the address of a buffer in the caller's address space.
+     Message buffers should be aligned on long-word boundaries.  The
+     message options OPTION are bit values, combined with bitwise-or.
+     One or both of `MACH_SEND_MSG' and `MACH_RCV_MSG' should be used.
+     Other options act as modifiers.  When sending a message, SEND_SIZE
+     specifies the size of the message buffer.  Otherwise zero should be
+     supplied.  When receiving a message, RCV_SIZE specifies the size
+     of the message buffer.  Otherwise zero should be supplied.  When
+     receiving a message, RCV_NAME specifies the port or port set.
+     Otherwise `MACH_PORT_NULL' should be supplied.  When using the
+     `MACH_SEND_TIMEOUT' and `MACH_RCV_TIMEOUT' options, TIMEOUT
+     specifies the time in milliseconds to wait before giving up.
+     Otherwise `MACH_MSG_TIMEOUT_NONE' should be supplied.  When using
+     the `MACH_SEND_NOTIFY', `MACH_SEND_CANCEL', and `MACH_RCV_NOTIFY'
+     options, NOTIFY specifies the port used for the notification.
+     Otherwise `MACH_PORT_NULL' should be supplied.
+
+     If the option argument is `MACH_SEND_MSG', it sends a message.  The
+     SEND_SIZE argument specifies the size of the message to send.  The
+     `msgh_remote_port' field of the message header specifies the
+     destination of the message.
+
+     If the option argument is `MACH_RCV_MSG', it receives a message.
+     The RCV_SIZE argument specifies the size of the message buffer
+     that will receive the message; messages larger than RCV_SIZE are
+     not received.  The RCV_NAME argument specifies the port or port
+     set from which to receive.
+
+     If the option argument is `MACH_SEND_MSG|MACH_RCV_MSG', then
+     `mach_msg' does both send and receive operations.  If the send
+     operation encounters an error (any return code other than
+     `MACH_MSG_SUCCESS'), then the call returns immediately without
+     attempting the receive operation.  Semantically the combined call
+     is equivalent to separate send and receive calls, but it saves a
+     system call and enables other internal optimizations.
+
+     If the option argument specifies neither `MACH_SEND_MSG' nor
+     `MACH_RCV_MSG', then `mach_msg' does nothing.
+
+     Some options, like `MACH_SEND_TIMEOUT' and `MACH_RCV_TIMEOUT',
+     share a supporting argument.  If these options are used together,
+     they make independent use of the supporting argument's value.
+
+ -- Data type: mach_msg_timeout_t
+     This is a `natural_t' used by the timeout mechanism.  The units are
+     milliseconds.  The value to be used when there is no timeout is
+     `MACH_MSG_TIMEOUT_NONE'.
+
+
+File: mach.info,  Node: Message Format,  Next: Exchanging Port Rights,  Prev: Mach Message Call,  Up: Messaging Interface
+
+4.2.2 Message Format
+--------------------
+
+A Mach message consists of a fixed size message header, a
+`mach_msg_header_t', followed by zero or more data items.  Data items
+are typed.  Each item has a type descriptor followed by the actual data
+(or the address of the data, for out-of-line memory regions).
+
+   The following data types are related to Mach ports:
+
+ -- Data type: mach_port_t
+     The `mach_port_t' data type is an unsigned integer type which
+     represents a port name in the task's port name space.  In GNU
+     Mach, this is an `unsigned int'.
+
+   The following data types are related to Mach messages:
+
+ -- Data type: mach_msg_bits_t
+     The `mach_msg_bits_t' data type is an `unsigned int' used to store
+     various flags for a message.
+
+ -- Data type: mach_msg_size_t
+     The `mach_msg_size_t' data type is an `unsigned int' used to store
+     the size of a message.
+
+ -- Data type: mach_msg_id_t
+     The `mach_msg_id_t' data type is an `integer_t' typically used to
+     convey a function or operation id for the receiver.
+
+ -- Data type: mach_msg_header_t
+     This structure is the start of every message in the Mach IPC
+     system.  It has the following members:
+
+    `mach_msg_bits_t msgh_bits'
+          The `msgh_bits' field has the following bits defined, all
+          other bits should be zero:
+
+         `MACH_MSGH_BITS_REMOTE_MASK'
+         `MACH_MSGH_BITS_LOCAL_MASK'
+               The remote and local bits encode `mach_msg_type_name_t'
+               values that specify the port rights in the
+               `msgh_remote_port' and `msgh_local_port' fields.  The
+               remote value must specify a send or send-once right for
+               the destination of the message.  If the local value
+               doesn't specify a send or send-once right for the
+               message's reply port, it must be zero and
+               msgh_local_port must be `MACH_PORT_NULL'.
+
+         `MACH_MSGH_BITS_COMPLEX'
+               The complex bit must be specified if the message body
+               contains port rights or out-of-line memory regions.  If
+               it is not specified, then the message body carries no
+               port rights or memory, no matter what the type
+               descriptors may seem to indicate.
+
+          `MACH_MSGH_BITS_REMOTE' and `MACH_MSGH_BITS_LOCAL' macros
+          return the appropriate `mach_msg_type_name_t' values, given a
+          `msgh_bits' value.  The `MACH_MSGH_BITS' macro constructs a
+          value for `msgh_bits', given two `mach_msg_type_name_t'
+          values.
+
+    `mach_msg_size_t msgh_size'
+          The `msgh_size' field in the header of a received message
+          contains the message's size.  The message size, a byte
+          quantity, includes the message header, type descriptors, and
+          in-line data.  For out-of-line memory regions, the message
+          size includes the size of the in-line address, not the size
+          of the actual memory region.  There are no arbitrary limits
+          on the size of a Mach message, the number of data items in a
+          message, or the size of the data items.
+
+    `mach_port_t msgh_remote_port'
+          The `msgh_remote_port' field specifies the destination port
+          of the message.  The field must carry a legitimate send or
+          send-once right for a port.
+
+    `mach_port_t msgh_local_port'
+          The `msgh_local_port' field specifies an auxiliary port right,
+          which is conventionally used as a reply port by the recipient
+          of the message.  The field must carry a send right, a
+          send-once right, `MACH_PORT_NULL', or `MACH_PORT_DEAD'.
+
+    `mach_port_seqno_t msgh_seqno'
+          The `msgh_seqno' field provides a sequence number for the
+          message.  It is only valid in received messages; its value in
+          sent messages is overwritten.
+
+    `mach_msg_id_t msgh_id'
+          The `mach_msg' call doesn't use the `msgh_id' field, but it
+          conventionally conveys an operation or function id.
+
+ -- Macro: mach_msg_bits_t MACH_MSGH_BITS (mach_msg_type_name_t REMOTE,
+          mach_msg_type_name_t LOCAL)
+     This macro composes two `mach_msg_type_name_t' values that specify
+     the port rights in the `msgh_remote_port' and `msgh_local_port'
+     fields of a `mach_msg' call into an appropriate `mach_msg_bits_t'
+     value.
+
+ -- Macro: mach_msg_type_name_t MACH_MSGH_BITS_REMOTE
+          (mach_msg_bits_t BITS)
+     This macro extracts the `mach_msg_type_name_t' value for the remote
+     port right in a `mach_msg_bits_t' value.
+
+ -- Macro: mach_msg_type_name_t MACH_MSGH_BITS_LOCAL
+          (mach_msg_bits_t BITS)
+     This macro extracts the `mach_msg_type_name_t' value for the local
+     port right in a `mach_msg_bits_t' value.
+
+ -- Macro: mach_msg_bits_t MACH_MSGH_BITS_PORTS (mach_msg_bits_t BITS)
+     This macro extracts the `mach_msg_bits_t' component consisting of
+     the `mach_msg_type_name_t' values for the remote and local port
+     right in a `mach_msg_bits_t' value.
+
+ -- Macro: mach_msg_bits_t MACH_MSGH_BITS_OTHER (mach_msg_bits_t BITS)
+     This macro extracts the `mach_msg_bits_t' component consisting of
+     everything except the `mach_msg_type_name_t' values for the remote
+     and local port right in a `mach_msg_bits_t' value.
+
+   Each data item has a type descriptor, a `mach_msg_type_t' or a
+`mach_msg_type_long_t'.  The `mach_msg_type_long_t' type descriptor
+allows larger values for some fields.  The `msgtl_header' field in the
+long descriptor is only used for its inline, longform, and deallocate
+bits.
+
+ -- Data type: mach_msg_type_name_t
+     This is an `unsigned int' and can be used to hold the `msgt_name'
+     component of the `mach_msg_type_t' and `mach_msg_type_long_t'
+     structure.
+
+ -- Data type: mach_msg_type_size_t
+     This is an `unsigned int' and can be used to hold the `msgt_size'
+     component of the `mach_msg_type_t' and `mach_msg_type_long_t'
+     structure.
+
+ -- Data type: mach_msg_type_number_t
+     This is an `natural_t' and can be used to hold the `msgt_number'
+     component of the `mach_msg_type_t' and `mach_msg_type_long_t'
+     structure.
+
+ -- Data type: mach_msg_type_t
+     This structure has the following members:
+
+    `unsigned int msgt_name : 8'
+          The `msgt_name' field specifies the data's type.  The
+          following types are predefined:
+
+         `MACH_MSG_TYPE_UNSTRUCTURED'
+
+         `MACH_MSG_TYPE_BIT'
+
+         `MACH_MSG_TYPE_BOOLEAN'
+
+         `MACH_MSG_TYPE_INTEGER_16'
+
+         `MACH_MSG_TYPE_INTEGER_32'
+
+         `MACH_MSG_TYPE_CHAR'
+
+         `MACH_MSG_TYPE_BYTE'
+
+         `MACH_MSG_TYPE_INTEGER_8'
+
+         `MACH_MSG_TYPE_REAL'
+
+         `MACH_MSG_TYPE_STRING'
+
+         `MACH_MSG_TYPE_STRING_C'
+
+         `MACH_MSG_TYPE_PORT_NAME'
+
+          The following predefined types specify port rights, and
+          receive special treatment.  The next section discusses these
+          types in detail.  The type `MACH_MSG_TYPE_PORT_NAME'
+          describes port right names, when no rights are being
+          transferred, but just names.  For this purpose, it should be
+          used in preference to `MACH_MSG_TYPE_INTEGER_32'.
+
+         `MACH_MSG_TYPE_MOVE_RECEIVE'
+
+         `MACH_MSG_TYPE_MOVE_SEND'
+
+         `MACH_MSG_TYPE_MOVE_SEND_ONCE'
+
+         `MACH_MSG_TYPE_COPY_SEND'
+
+         `MACH_MSG_TYPE_MAKE_SEND'
+
+         `MACH_MSG_TYPE_MAKE_SEND_ONCE'
+
+    `msgt_size : 8'
+          The `msgt_size' field specifies the size of each datum, in
+          bits.  For example, the msgt_size of
+          `MACH_MSG_TYPE_INTEGER_32' data is 32.
+
+    `msgt_number : 12'
+          The `msgt_number' field specifies how many data elements
+          comprise the data item.  Zero is a legitimate number.
+
+          The total length specified by a type descriptor is
+          `(msgt_size * msgt_number)', rounded up to an integral number
+          of bytes.  In-line data is then padded to an integral number
+          of long-words.  This ensures that type descriptors always
+          start on long-word boundaries.  It implies that message sizes
+          are always an integral multiple of a long-word's size.
+
+    `msgt_inline : 1'
+          The `msgt_inline' bit specifies, when `FALSE', that the data
+          actually resides in an out-of-line region.  The address of
+          the memory region (a `vm_offset_t' or `vm_address_t') follows
+          the type descriptor in the message body.  The `msgt_name',
+          `msgt_size', and `msgt_number' fields describe the memory
+          region, not the address.
+
+    `msgt_longform : 1'
+          The `msgt_longform' bit specifies, when `TRUE', that this type
+          descriptor is a `mach_msg_type_long_t' instead of a
+          `mach_msg_type_t'.  The `msgt_name', `msgt_size', and
+          `msgt_number' fields should be zero.  Instead, `mach_msg' uses
+          the following `msgtl_name', `msgtl_size', and `msgtl_number'
+          fields.
+
+    `msgt_deallocate : 1'
+          The `msgt_deallocate' bit is used with out-of-line regions.
+          When `TRUE', it specifies that the memory region should be
+          deallocated from the sender's address space (as if with
+          `vm_deallocate') when the message is sent.
+
+    `msgt_unused : 1'
+          The `msgt_unused' bit should be zero.
+
+ -- Macro: boolean_t MACH_MSG_TYPE_PORT_ANY (mach_msg_type_name_t type)
+     This macro returns `TRUE' if the given type name specifies a port
+     type, otherwise it returns `FALSE'.
+
+ -- Macro: boolean_t MACH_MSG_TYPE_PORT_ANY_SEND (mach_msg_type_name_t
+          type)
+     This macro returns `TRUE' if the given type name specifies a port
+     type with a send or send-once right, otherwise it returns `FALSE'.
+
+ -- Macro: boolean_t MACH_MSG_TYPE_PORT_ANY_RIGHT (mach_msg_type_name_t
+          type)
+     This macro returns `TRUE' if the given type name specifies a port
+     right type which is moved, otherwise it returns `FALSE'.
+
+ -- Data type: mach_msg_type_long_t
+     This structure has the following members:
+
+    `mach_msg_type_t msgtl_header'
+          Same meaning as `msgt_header'.
+
+    `unsigned short msgtl_name'
+          Same meaning as `msgt_name'.
+
+    `unsigned short msgtl_size'
+          Same meaning as `msgt_size'.
+
+    `unsigned int msgtl_number'
+          Same meaning as `msgt_number'.
+
+
+File: mach.info,  Node: Exchanging Port Rights,  Next: Memory,  Prev: Message Format,  Up: Messaging Interface
+
+4.2.3 Exchanging Port Rights
+----------------------------
+
+Each task has its own space of port rights.  Port rights are named with
+positive integers.  Except for the reserved values
+`MACH_PORT_NULL (0)'(1) and `MACH_PORT_DEAD (~0)', this is a full 32-bit
+name space.  When the kernel chooses a name for a new right, it is free
+to pick any unused name (one which denotes no right) in the space.
+
+   There are five basic kinds of rights: receive rights, send rights,
+send-once rights, port-set rights, and dead names.  Dead names are not
+capabilities.  They act as place-holders to prevent a name from being
+otherwise used.
+
+   A port is destroyed, or dies, when its receive right is deallocated.
+When a port dies, send and send-once rights for the port turn into dead
+names.  Any messages queued at the port are destroyed, which deallocates
+the port rights and out-of-line memory in the messages.
+
+   Tasks may hold multiple user-references for send rights and dead
+names.  When a task receives a send right which it already holds, the
+kernel increments the right's user-reference count.  When a task
+deallocates a send right, the kernel decrements its user-reference
+count, and the task only loses the send right when the count goes to
+zero.
+
+   Send-once rights always have a user-reference count of one, although
+a port can have multiple send-once rights, because each send-once right
+held by a task has a different name.  In contrast, when a task holds
+send rights or a receive right for a port, the rights share a single
+name.
+
+   A message body can carry port rights; the `msgt_name' (`msgtl_name')
+field in a type descriptor specifies the type of port right and how the
+port right is to be extracted from the caller.  The values
+`MACH_PORT_NULL' and `MACH_PORT_DEAD' are always valid in place of a
+port right in a message body.  In a sent message, the following
+`msgt_name' values denote port rights:
+
+`MACH_MSG_TYPE_MAKE_SEND'
+     The message will carry a send right, but the caller must supply a
+     receive right.  The send right is created from the receive right,
+     and the receive right's make-send count is incremented.
+
+`MACH_MSG_TYPE_COPY_SEND'
+     The message will carry a send right, and the caller should supply
+     a send right.  The user reference count for the supplied send
+     right is not changed.  The caller may also supply a dead name and
+     the receiving task will get `MACH_PORT_DEAD'.
+
+`MACH_MSG_TYPE_MOVE_SEND'
+     The message will carry a send right, and the caller should supply
+     a send right.  The user reference count for the supplied send
+     right is decremented, and the right is destroyed if the count
+     becomes zero.  Unless a receive right remains, the name becomes
+     available for recycling.  The caller may also supply a dead name,
+     which loses a user reference, and the receiving task will get
+     `MACH_PORT_DEAD'.
+
+`MACH_MSG_TYPE_MAKE_SEND_ONCE'
+     The message will carry a send-once right, but the caller must
+     supply a receive right.  The send-once right is created from the
+     receive right.
+
+`MACH_MSG_TYPE_MOVE_SEND_ONCE'
+     The message will carry a send-once right, and the caller should
+     supply a send-once right.  The caller loses the supplied send-once
+     right.  The caller may also supply a dead name, which loses a user
+     reference, and the receiving task will get `MACH_PORT_DEAD'.
+
+`MACH_MSG_TYPE_MOVE_RECEIVE'
+     The message will carry a receive right, and the caller should
+     supply a receive right.  The caller loses the supplied receive
+     right, but retains any send rights with the same name.
+
+   If a message carries a send or send-once right, and the port dies
+while the message is in transit, then the receiving task will get
+`MACH_PORT_DEAD' instead of a right.  The following `msgt_name' values
+in a received message indicate that it carries port rights:
+
+`MACH_MSG_TYPE_PORT_SEND'
+     This name is an alias for `MACH_MSG_TYPE_MOVE_SEND'.  The message
+     carried a send right.  If the receiving task already has send
+     and/or receive rights for the port, then that name for the port
+     will be reused.  Otherwise, the new right will have a new name.
+     If the task already has send rights, it gains a user reference for
+     the right (unless this would cause the user-reference count to
+     overflow).  Otherwise, it acquires the send right, with a
+     user-reference count of one.
+
+`MACH_MSG_TYPE_PORT_SEND_ONCE'
+     This name is an alias for `MACH_MSG_TYPE_MOVE_SEND_ONCE'.  The
+     message carried a send-once right.  The right will have a new name.
+
+`MACH_MSG_TYPE_PORT_RECEIVE'
+     This name is an alias for `MACH_MSG_TYPE_MOVE_RECEIVE'.  The
+     message carried a receive right.  If the receiving task already
+     has send rights for the port, then that name for the port will be
+     reused.  Otherwise, the right will have a new name.  The make-send
+     count of the receive right is reset to zero, but the port retains
+     other attributes like queued messages, extant send and send-once
+     rights, and requests for port-destroyed and no-senders
+     notifications.
+
+   When the kernel chooses a new name for a port right, it can choose
+any name, other than `MACH_PORT_NULL' and `MACH_PORT_DEAD', which is
+not currently being used for a port right or dead name.  It might
+choose a name which at some previous time denoted a port right, but is
+currently unused.
+
+   ---------- Footnotes ----------
+
+   (1) In the Hurd system, we don't make the assumption that
+`MACH_PORT_NULL' is zero and evaluates to false, but rather compare
+port names to `MACH_PORT_NULL' explicitely
+
+
+File: mach.info,  Node: Memory,  Next: Message Send,  Prev: Exchanging Port Rights,  Up: Messaging Interface
+
+4.2.4 Memory
+------------
+
+A message body can contain the address of a region in the sender's
+address space which should be transferred as part of the message.  The
+message carries a logical copy of the memory, but the kernel uses VM
+techniques to defer any actual page copies.  Unless the sender or the
+receiver modifies the data, the physical pages remain shared.
+
+   An out-of-line transfer occurs when the data's type descriptor
+specifies `msgt_inline' as `FALSE'.  The address of the memory region (a
+`vm_offset_t' or `vm_address_t') should follow the type descriptor in
+the message body.  The type descriptor and the address contribute to
+the message's size (`send_size', `msgh_size').  The out-of-line data
+does not contribute to the message's size.
+
+   The name, size, and number fields in the type descriptor describe the
+type and length of the out-of-line data, not the in-line address.
+Out-of-line memory frequently requires long type descriptors
+(`mach_msg_type_long_t'), because the `msgt_number' field is too small
+to describe a page of 4K bytes.
+
+   Out-of-line memory arrives somewhere in the receiver's address space
+as new memory.  It has the same inheritance and protection attributes as
+newly `vm_allocate''d memory.  The receiver has the responsibility of
+deallocating (with `vm_deallocate') the memory when it is no longer
+needed.  Security-conscious receivers should exercise caution when
+using out-of-line memory from untrustworthy sources, because the memory
+may be backed by an unreliable memory manager.
+
+   Null out-of-line memory is legal.  If the out-of-line region size is
+zero (for example, because `msgtl_number' is zero), then the region's
+specified address is ignored.  A received null out-of-line memory
+region always has a zero address.
+
+   Unaligned addresses and region sizes that are not page multiples are
+legal.  A received message can also contain memory with unaligned
+addresses and funny sizes.  In the general case, the first and last
+pages in the new memory region in the receiver do not contain only data
+from the sender, but are partly zero.(1)  The received address points
+to the start of the data in the first page.  This possibility doesn't
+complicate deallocation, because `vm_deallocate' does the right thing,
+rounding the start address down and the end address up to deallocate
+all arrived pages.
+
+   Out-of-line memory has a deallocate option, controlled by the
+`msgt_deallocate' bit.  If it is `TRUE' and the out-of-line memory
+region is not null, then the region is implicitly deallocated from the
+sender, as if by `vm_deallocate'.  In particular, the start and end
+addresses are rounded so that every page overlapped by the memory
+region is deallocated.  The use of `msgt_deallocate' effectively
+changes the memory copy into a memory movement.  In a received message,
+`msgt_deallocate' is `TRUE' in type descriptors for out-of-line memory.
+
+   Out-of-line memory can carry port rights.
+
+   ---------- Footnotes ----------
+
+   (1) Sending out-of-line memory with a non-page-aligned address, or a
+size which is not a page multiple, works but with a caveat.  The extra
+bytes in the first and last page of the received memory are not zeroed,
+so the receiver can peek at more data than the sender intended to
+transfer.  This might be a security problem for the sender.
+
+
+File: mach.info,  Node: Message Send,  Next: Message Receive,  Prev: Memory,  Up: Messaging Interface
+
+4.2.5 Message Send
+------------------
+
+The send operation queues a message to a port.  The message carries a
+copy of the caller's data.  After the send, the caller can freely modify
+the message buffer or the out-of-line memory regions and the message
+contents will remain unchanged.
+
+   Message delivery is reliable and sequenced.  Messages are not lost,
+and messages sent to a port, from a single thread, are received in the
+order in which they were sent.
+
+   If the destination port's queue is full, then several things can
+happen.  If the message is sent to a send-once right (`msgh_remote_port'
+carries a send-once right), then the kernel ignores the queue limit and
+delivers the message.  Otherwise the caller blocks until there is room
+in the queue, unless the `MACH_SEND_TIMEOUT' or `MACH_SEND_NOTIFY'
+options are used.  If a port has several blocked senders, then any of
+them may queue the next message when space in the queue becomes
+available, with the proviso that a blocked sender will not be
+indefinitely starved.
+
+   These options modify `MACH_SEND_MSG'.  If `MACH_SEND_MSG' is not
+also specified, they are ignored.
+
+`MACH_SEND_TIMEOUT'
+     The timeout argument should specify a maximum time (in
+     milliseconds) for the call to block before giving up.(1)  If the
+     message can't be queued before the timeout interval elapses, then
+     the call returns `MACH_SEND_TIMED_OUT'.  A zero timeout is
+     legitimate.
+
+`MACH_SEND_NOTIFY'
+     The notify argument should specify a receive right for a notify
+     port.  If the send were to block, then instead the message is
+     queued, `MACH_SEND_WILL_NOTIFY' is returned, and a msg-accepted
+     notification is requested.  If `MACH_SEND_TIMEOUT' is also
+     specified, then `MACH_SEND_NOTIFY' doesn't take effect until the
+     timeout interval elapses.
+
+     With `MACH_SEND_NOTIFY', a task can forcibly queue to a send right
+     one message at a time.  A msg-accepted notification is sent to the
+     the notify port when another message can be forcibly queued.  If
+     an attempt is made to use `MACH_SEND_NOTIFY' before then, the call
+     returns a `MACH_SEND_NOTIFY_IN_PROGRESS' error.
+
+     The msg-accepted notification carries the name of the send right.
+     If the send right is deallocated before the msg-accepted
+     notification is generated, then the msg-accepted notification
+     carries the value `MACH_PORT_NULL'.  If the destination port is
+     destroyed before the notification is generated, then a send-once
+     notification is generated instead.
+
+`MACH_SEND_INTERRUPT'
+     If specified, the `mach_msg' call will return
+     `MACH_SEND_INTERRUPTED' if a software interrupt aborts the call.
+     Otherwise, the send operation will be retried.
+
+`MACH_SEND_CANCEL'
+     The notify argument should specify a receive right for a notify
+     port.  If the send operation removes the destination port right
+     from the caller, and the removed right had a dead-name request
+     registered for it, and notify is the notify port for the dead-name
+     request, then the dead-name request may be silently canceled
+     (instead of resulting in a port-deleted notification).
+
+     This option is typically used to cancel a dead-name request made
+     with the `MACH_RCV_NOTIFY' option.  It should only be used as an
+     optimization.
+
+   The send operation can generate the following return codes.  These
+return codes imply that the call did nothing:
+
+`MACH_SEND_MSG_TOO_SMALL'
+     The specified send_size was smaller than the minimum size for a
+     message.
+
+`MACH_SEND_NO_BUFFER'
+     A resource shortage prevented the kernel from allocating a message
+     buffer.
+
+`MACH_SEND_INVALID_DATA'
+     The supplied message buffer was not readable.
+
+`MACH_SEND_INVALID_HEADER'
+     The `msgh_bits' value was invalid.
+
+`MACH_SEND_INVALID_DEST'
+     The `msgh_remote_port' value was invalid.
+
+`MACH_SEND_INVALID_REPLY'
+     The `msgh_local_port' value was invalid.
+
+`MACH_SEND_INVALID_NOTIFY'
+     When using `MACH_SEND_CANCEL', the notify argument did not denote a
+     valid receive right.
+
+   These return codes imply that some or all of the message was
+destroyed:
+
+`MACH_SEND_INVALID_MEMORY'
+     The message body specified out-of-line data that was not readable.
+
+`MACH_SEND_INVALID_RIGHT'
+     The message body specified a port right which the caller didn't
+     possess.
+
+`MACH_SEND_INVALID_TYPE'
+     A type descriptor was invalid.
+
+`MACH_SEND_MSG_TOO_SMALL'
+     The last data item in the message ran over the end of the message.
+
+   These return codes imply that the message was returned to the caller
+with a pseudo-receive operation:
+
+`MACH_SEND_TIMED_OUT'
+     The timeout interval expired.
+
+`MACH_SEND_INTERRUPTED'
+     A software interrupt occurred.
+
+`MACH_SEND_INVALID_NOTIFY'
+     When using `MACH_SEND_NOTIFY', the notify argument did not denote a
+     valid receive right.
+
+`MACH_SEND_NO_NOTIFY'
+     A resource shortage prevented the kernel from setting up a
+     msg-accepted notification.
+
+`MACH_SEND_NOTIFY_IN_PROGRESS'
+     A msg-accepted notification was already requested, and hasn't yet
+     been generated.
+
+   These return codes imply that the message was queued:
+
+`MACH_SEND_WILL_NOTIFY'
+     The message was forcibly queued, and a msg-accepted notification
+     was requested.
+
+`MACH_MSG_SUCCESS'
+     The message was queued.
+
+   Some return codes, like `MACH_SEND_TIMED_OUT', imply that the
+message was almost sent, but could not be queued.  In these situations,
+the kernel tries to return the message contents to the caller with a
+pseudo-receive operation.  This prevents the loss of port rights or
+memory which only exist in the message.  For example, a receive right
+which was moved into the message, or out-of-line memory sent with the
+deallocate bit.
+
+   The pseudo-receive operation is very similar to a normal receive
+operation.  The pseudo-receive handles the port rights in the message
+header as if they were in the message body.  They are not reversed.
+After the pseudo-receive, the message is ready to be resent.  If the
+message is not resent, note that out-of-line memory regions may have
+moved and some port rights may have changed names.
+
+   The pseudo-receive operation may encounter resource shortages.  This
+is similar to a `MACH_RCV_BODY_ERROR' return code from a receive
+operation.  When this happens, the normal send return codes are
+augmented with the `MACH_MSG_IPC_SPACE', `MACH_MSG_VM_SPACE',
+`MACH_MSG_IPC_KERNEL', and `MACH_MSG_VM_KERNEL' bits to indicate the
+nature of the resource shortage.
+
+   The queueing of a message carrying receive rights may create a
+circular loop of receive rights and messages, which can never be
+received.  For example, a message carrying a receive right can be sent
+to that receive right.  This situation is not an error, but the kernel
+will garbage-collect such loops, destroying the messages and ports
+involved.
+
+   ---------- Footnotes ----------
+
+   (1) If MACH_SEND_TIMEOUT is used without MACH_SEND_INTERRUPT, then
+the timeout duration might not be accurate.  When the call is
+interrupted and automatically retried, the original timeout is used.
+If interrupts occur frequently enough, the timeout interval might never
+expire.
+
+
+File: mach.info,  Node: Message Receive,  Next: Atomicity,  Prev: Message Send,  Up: Messaging Interface
+
+4.2.6 Message Receive
+---------------------
+
+The receive operation dequeues a message from a port.  The receiving
+task acquires the port rights and out-of-line memory regions carried in
+the message.
+
+   The `rcv_name' argument specifies a port or port set from which to
+receive.  If a port is specified, the caller must possess the receive
+right for the port and the port must not be a member of a port set.  If
+no message is present, then the call blocks, subject to the
+`MACH_RCV_TIMEOUT' option.
+
+   If a port set is specified, the call will receive a message sent to
+any of the member ports.  It is permissible for the port set to have no
+member ports, and ports may be added and removed while a receive from
+the port set is in progress.  The received message can come from any of
+the member ports which have messages, with the proviso that a member
+port with messages will not be indefinitely starved.  The
+`msgh_local_port' field in the received message header specifies from
+which port in the port set the message came.
+
+   The `rcv_size' argument specifies the size of the caller's message
+buffer.  The `mach_msg' call will not receive a message larger than
+`rcv_size'.  Messages that are too large are destroyed, unless the
+`MACH_RCV_LARGE' option is used.
+
+   The destination and reply ports are reversed in a received message
+header.  The `msgh_local_port' field names the destination port, from
+which the message was received, and the `msgh_remote_port' field names
+the reply port right.  The bits in `msgh_bits' are also reversed.  The
+`MACH_MSGH_BITS_LOCAL' bits have the value `MACH_MSG_TYPE_PORT_SEND' if
+the message was sent to a send right, and the value
+`MACH_MSG_TYPE_PORT_SEND_ONCE' if was sent to a send-once right.  The
+`MACH_MSGH_BITS_REMOTE' bits describe the reply port right.
+
+   A received message can contain port rights and out-of-line memory.
+The `msgh_local_port' field does not receive a port right; the act of
+receiving the message destroys the send or send-once right for the
+destination port.  The msgh_remote_port field does name a received port
+right, the reply port right, and the message body can carry port rights
+and memory if `MACH_MSGH_BITS_COMPLEX' is present in msgh_bits.
+Received port rights and memory should be consumed or deallocated in
+some fashion.
+
+   In almost all cases, `msgh_local_port' will specify the name of a
+receive right, either `rcv_name' or if `rcv_name' is a port set, a
+member of `rcv_name'.  If other threads are concurrently manipulating
+the receive right, the situation is more complicated.  If the receive
+right is renamed during the call, then `msgh_local_port' specifies the
+right's new name.  If the caller loses the receive right after the
+message was dequeued from it, then `mach_msg' will proceed instead of
+returning `MACH_RCV_PORT_DIED'.  If the receive right was destroyed,
+then `msgh_local_port' specifies `MACH_PORT_DEAD'.  If the receive
+right still exists, but isn't held by the caller, then
+`msgh_local_port' specifies `MACH_PORT_NULL'.
+
+   Received messages are stamped with a sequence number, taken from the
+port from which the message was received.  (Messages received from a
+port set are stamped with a sequence number from the appropriate member
+port.)  Newly created ports start with a zero sequence number, and the
+sequence number is reset to zero whenever the port's receive right moves
+between tasks.  When a message is dequeued from the port, it is stamped
+with the port's sequence number and the port's sequence number is then
+incremented.  The dequeue and increment operations are atomic, so that
+multiple threads receiving messages from a port can use the
+`msgh_seqno' field to reconstruct the original order of the messages.
+
+   These options modify `MACH_RCV_MSG'.  If `MACH_RCV_MSG' is not also
+specified, they are ignored.
+
+`MACH_RCV_TIMEOUT'
+     The timeout argument should specify a maximum time (in
+     milliseconds) for the call to block before giving up.(1)  If no
+     message arrives before the timeout interval elapses, then the call
+     returns `MACH_RCV_TIMED_OUT'.  A zero timeout is legitimate.
+
+`MACH_RCV_NOTIFY'
+     The notify argument should specify a receive right for a notify
+     port.  If receiving the reply port creates a new port right in the
+     caller, then the notify port is used to request a dead-name
+     notification for the new port right.
+
+`MACH_RCV_INTERRUPT'
+     If specified, the `mach_msg' call will return
+     `MACH_RCV_INTERRUPTED' if a software interrupt aborts the call.
+     Otherwise, the receive operation will be retried.
+
+`MACH_RCV_LARGE'
+     If the message is larger than `rcv_size', then the message remains
+     queued instead of being destroyed.  The call returns
+     `MACH_RCV_TOO_LARGE' and the actual size of the message is returned
+     in the `msgh_size' field of the message header.
+
+   The receive operation can generate the following return codes.  These
+return codes imply that the call did not dequeue a message:
+
+`MACH_RCV_INVALID_NAME'
+     The specified `rcv_name' was invalid.
+
+`MACH_RCV_IN_SET'
+     The specified port was a member of a port set.
+
+`MACH_RCV_TIMED_OUT'
+     The timeout interval expired.
+
+`MACH_RCV_INTERRUPTED'
+     A software interrupt occurred.
+
+`MACH_RCV_PORT_DIED'
+     The caller lost the rights specified by `rcv_name'.
+
+`MACH_RCV_PORT_CHANGED'
+     `rcv_name' specified a receive right which was moved into a port
+     set during the call.
+
+`MACH_RCV_TOO_LARGE'
+     When using `MACH_RCV_LARGE', and the message was larger than
+     `rcv_size'.  The message is left queued, and its actual size is
+     returned in the `msgh_size' field of the message buffer.
+
+   These return codes imply that a message was dequeued and destroyed:
+
+`MACH_RCV_HEADER_ERROR'
+     A resource shortage prevented the reception of the port rights in
+     the message header.
+
+`MACH_RCV_INVALID_NOTIFY'
+     When using `MACH_RCV_NOTIFY', the notify argument did not denote a
+     valid receive right.
+
+`MACH_RCV_TOO_LARGE'
+     When not using `MACH_RCV_LARGE', a message larger than `rcv_size'
+     was dequeued and destroyed.
+
+   In these situations, when a message is dequeued and then destroyed,
+the reply port and all port rights and memory in the message body are
+destroyed.  However, the caller receives the message's header, with all
+fields correct, including the destination port but excepting the reply
+port, which is `MACH_PORT_NULL'.
+
+   These return codes imply that a message was received:
+
+`MACH_RCV_BODY_ERROR'
+     A resource shortage prevented the reception of a port right or
+     out-of-line memory region in the message body.  The message header,
+     including the reply port, is correct.  The kernel attempts to
+     transfer all port rights and memory regions in the body, and only
+     destroys those that can't be transferred.
+
+`MACH_RCV_INVALID_DATA'
+     The specified message buffer was not writable.  The calling task
+     did successfully receive the port rights and out-of-line memory
+     regions in the message.
+
+`MACH_MSG_SUCCESS'
+     A message was received.
+
+   Resource shortages can occur after a message is dequeued, while
+transferring port rights and out-of-line memory regions to the receiving
+task.  The `mach_msg' call returns `MACH_RCV_HEADER_ERROR' or
+`MACH_RCV_BODY_ERROR' in this situation.  These return codes always
+carry extra bits (bitwise-ored) that indicate the nature of the resource
+shortage:
+
+`MACH_MSG_IPC_SPACE'
+     There was no room in the task's IPC name space for another port
+     name.
+
+`MACH_MSG_VM_SPACE'
+     There was no room in the task's VM address space for an out-of-line
+     memory region.
+
+`MACH_MSG_IPC_KERNEL'
+     A kernel resource shortage prevented the reception of a port right.
+
+`MACH_MSG_VM_KERNEL'
+     A kernel resource shortage prevented the reception of an
+     out-of-line memory region.
+
+   If a resource shortage prevents the reception of a port right, the
+port right is destroyed and the caller sees the name `MACH_PORT_NULL'.
+If a resource shortage prevents the reception of an out-of-line memory
+region, the region is destroyed and the caller receives a zero address.
+In addition, the `msgt_size' (`msgtl_size') field in the data's type
+descriptor is changed to zero.  If a resource shortage prevents the
+reception of out-of-line memory carrying port rights, then the port
+rights are always destroyed if the memory region can not be received.
+A task never receives port rights or memory regions that it isn't told
+about.
+
+   ---------- Footnotes ----------
+
+   (1) If MACH_RCV_TIMEOUT is used without MACH_RCV_INTERRUPT, then the
+timeout duration might not be accurate.  When the call is interrupted
+and automatically retried, the original timeout is used.  If interrupts
+occur frequently enough, the timeout interval might never expire.
+
+
+File: mach.info,  Node: Atomicity,  Prev: Message Receive,  Up: Messaging Interface
+
+4.2.7 Atomicity
+---------------
+
+The `mach_msg' call handles port rights in a message header atomically.
+Port rights and out-of-line memory in a message body do not enjoy this
+atomicity guarantee.  The message body may be processed front-to-back,
+back-to-front, first out-of-line memory then port rights, in some
+random order, or even atomically.
+
+   For example, consider sending a message with the destination port
+specified as `MACH_MSG_TYPE_MOVE_SEND' and the reply port specified as
+`MACH_MSG_TYPE_COPY_SEND'.  The same send right, with one
+user-reference, is supplied for both the `msgh_remote_port' and
+`msgh_local_port' fields.  Because `mach_msg' processes the message
+header atomically, this succeeds.  If `msgh_remote_port' were processed
+before `msgh_local_port', then `mach_msg' would return
+`MACH_SEND_INVALID_REPLY' in this situation.
+
+   On the other hand, suppose the destination and reply port are both
+specified as `MACH_MSG_TYPE_MOVE_SEND', and again the same send right
+with one user-reference is supplied for both.  Now the send operation
+fails, but because it processes the header atomically, mach_msg can
+return either `MACH_SEND_INVALID_DEST' or `MACH_SEND_INVALID_REPLY'.
+
+   For example, consider receiving a message at the same time another
+thread is deallocating the destination receive right.  Suppose the reply
+port field carries a send right for the destination port.  If the
+deallocation happens before the dequeuing, then the receiver gets
+`MACH_RCV_PORT_DIED'.  If the deallocation happens after the receive,
+then the `msgh_local_port' and the `msgh_remote_port' fields both
+specify the same right, which becomes a dead name when the receive
+right is deallocated.  If the deallocation happens between the dequeue
+and the receive, then the `msgh_local_port' and `msgh_remote_port'
+fields both specify `MACH_PORT_DEAD'.  Because the header is processed
+atomically, it is not possible for just one of the two fields to hold
+`MACH_PORT_DEAD'.
+
+   The `MACH_RCV_NOTIFY' option provides a more likely example.
+Suppose a message carrying a send-once right reply port is received with
+`MACH_RCV_NOTIFY' at the same time the reply port is destroyed.  If the
+reply port is destroyed first, then `msgh_remote_port' specifies
+`MACH_PORT_DEAD' and the kernel does not generate a dead-name
+notification.  If the reply port is destroyed after it is received,
+then `msgh_remote_port' specifies a dead name for which the kernel
+generates a dead-name notification.  It is not possible to receive the
+reply port right and have it turn into a dead name before the dead-name
+notification is requested; as part of the message header the reply port
+is received atomically.
+
+
+File: mach.info,  Node: Port Manipulation Interface,  Prev: Messaging Interface,  Up: Inter Process Communication
+
+4.3 Port Manipulation Interface
+===============================
+
+This section describes the interface to create, destroy and manipulate
+ports, port rights and port sets.
+
+ -- Data type: ipc_space_t
+     This is a `task_t' (and as such a `mach_port_t'), which holds a
+     port name associated with a port that represents an IPC space in
+     the kernel.  An IPC space is used by the kernel to manage the port
+     names and rights available to a task.  The IPC space doesn't get a
+     port name of its own.  Instead the port name of the task
+     containing the IPC space is used to name the IPC space of the task
+     (as is indicated by the fact that the type of `ipc_space_t' is
+     actually `task_t').
+
+     The IPC spaces of tasks are the only ones accessible outside of
+     the kernel.
+
+* Menu:
+
+* Port Creation::                 How to create new ports and port sets.
+* Port Destruction::              How to destroy ports and port sets.
+* Port Names::                    How to query and manipulate port names.
+* Port Rights::                   How to work with port rights.
+* Ports and other Tasks::         How to move rights between tasks.
+* Receive Rights::                How to work with receive rights.
+* Port Sets::                     How to work with port sets.
+* Request Notifications::         How to request notifications for events.
+
+
+File: mach.info,  Node: Port Creation,  Next: Port Destruction,  Up: Port Manipulation Interface
+
+4.3.1 Port Creation
+-------------------
+
+ -- Function: kern_return_t mach_port_allocate (ipc_space_t TASK,
+          mach_port_right_t RIGHT, mach_port_t *NAME)
+     The `mach_port_allocate' function creates a new right in the
+     specified task.  The new right's name is returned in NAME, which
+     may be any name that wasn't in use.
+
+     The RIGHT argument takes the following values:
+
+    `MACH_PORT_RIGHT_RECEIVE'
+          `mach_port_allocate' creates a port.  The new port is not a
+          member of any port set.  It doesn't have any extant send or
+          send-once rights.  Its make-send count is zero, its sequence
+          number is zero, its queue limit is
+          `MACH_PORT_QLIMIT_DEFAULT', and it has no queued messages.
+          NAME denotes the receive right for the new port.
+
+          TASK does not hold send rights for the new port, only the
+          receive right.  `mach_port_insert_right' and
+          `mach_port_extract_right' can be used to convert the receive
+          right into a combined send/receive right.
+
+    `MACH_PORT_RIGHT_PORT_SET'
+          `mach_port_allocate' creates a port set.  The new port set
+          has no members.
+
+    `MACH_PORT_RIGHT_DEAD_NAME'
+          `mach_port_allocate' creates a dead name.  The new dead name
+          has one user reference.
+
+     The function returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_VALUE' if
+     RIGHT was invalid, `KERN_NO_SPACE' if there was no room in TASK's
+     IPC name space for another right and `KERN_RESOURCE_SHORTAGE' if
+     the kernel ran out of memory.
+
+     The `mach_port_allocate' call is actually an RPC to TASK, normally
+     a send right for a task port, but potentially any send right.  In
+     addition to the normal diagnostic return codes from the call's
+     server (normally the kernel), the call may return `mach_msg'
+     return codes.
+
+ -- Function: mach_port_t mach_reply_port ()
+     The `mach_reply_port' system call creates a reply port in the
+     calling task.
+
+     `mach_reply_port' creates a port, giving the calling task the
+     receive right for the port.  The call returns the name of the new
+     receive right.
+
+     This is very much like creating a receive right with the
+     `mach_port_allocate' call, with two differences.  First,
+     `mach_reply_port' is a system call and not an RPC (which requires a
+     reply port).  Second, the port created by `mach_reply_port' may be
+     optimized for use as a reply port.
+
+     The function returns `MACH_PORT_NULL' if a resource shortage
+     prevented the creation of the receive right.
+
+ -- Function: kern_return_t mach_port_allocate_name (ipc_space_t TASK,
+          mach_port_right_t RIGHT, mach_port_t NAME)
+     The function `mach_port_allocate_name' creates a new right in the
+     specified task, with a specified name for the new right.  NAME
+     must not already be in use for some right, and it can't be the
+     reserved values `MACH_PORT_NULL' and `MACH_PORT_DEAD'.
+
+     The RIGHT argument takes the following values:
+
+    `MACH_PORT_RIGHT_RECEIVE'
+          `mach_port_allocate_name' creates a port.  The new port is
+          not a member of any port set.  It doesn't have any extant
+          send or send-once rights.  Its make-send count is zero, its
+          sequence number is zero, its queue limit is
+          `MACH_PORT_QLIMIT_DEFAULT', and it has no queued messages.
+          NAME denotes the receive right for the new port.
+
+          TASK does not hold send rights for the new port, only the
+          receive right.  `mach_port_insert_right' and
+          `mach_port_extract_right' can be used to convert the receive
+          right into a combined send/receive right.
+
+    `MACH_PORT_RIGHT_PORT_SET'
+          `mach_port_allocate_name' creates a port set.  The new port
+          set has no members.
+
+    `MACH_PORT_RIGHT_DEAD_NAME'
+          `mach_port_allocate_name' creates a new dead name.  The new
+          dead name has one user reference.
+
+     The function returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_VALUE' if
+     RIGHT was invalid or NAME was `MACH_PORT_NULL' or
+     `MACH_PORT_DEAD', `KERN_NAME_EXISTS' if NAME was already in use
+     for a port right and `KERN_RESOURCE_SHORTAGE' if the kernel ran
+     out of memory.
+
+     The `mach_port_allocate_name' call is actually an RPC to TASK,
+     normally a send right for a task port, but potentially any send
+     right.  In addition to the normal diagnostic return codes from the
+     call's server (normally the kernel), the call may return `mach_msg'
+     return codes.
+
+
+File: mach.info,  Node: Port Destruction,  Next: Port Names,  Prev: Port Creation,  Up: Port Manipulation Interface
+
+4.3.2 Port Destruction
+----------------------
+
+ -- Function: kern_return_t mach_port_deallocate (ipc_space_t TASK,
+          mach_port_t NAME)
+     The function `mach_port_deallocate' releases a user reference for a
+     right in TASK's IPC name space.  It allows a task to release a
+     user reference for a send or send-once right without failing if
+     the port has died and the right is now actually a dead name.
+
+     If NAME denotes a dead name, send right, or send-once right, then
+     the right loses one user reference.  If it only had one user
+     reference, then the right is destroyed.
+
+     The function returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_NAME' if
+     NAME did not denote a right and `KERN_INVALID_RIGHT' if NAME
+     denoted an invalid right.
+
+     The `mach_port_deallocate' call is actually an RPC to TASK,
+     normally a send right for a task port, but potentially any send
+     right.  In addition to the normal diagnostic return codes from the
+     call's server (normally the kernel), the call may return `mach_msg'
+     return codes.
+
+ -- Function: kern_return_t mach_port_destroy (ipc_space_t TASK,
+          mach_port_t NAME)
+     The function `mach_port_destroy' deallocates all rights denoted by
+     a name.  The name becomes immediately available for reuse.
+
+     For most purposes, `mach_port_mod_refs' and `mach_port_deallocate'
+     are preferable.
+
+     If NAME denotes a port set, then all members of the port set are
+     implicitly removed from the port set.
+
+     If NAME denotes a receive right that is a member of a port set,
+     the receive right is implicitly removed from the port set.  If
+     there is a port-destroyed request registered for the port, then
+     the receive right is not actually destroyed, but instead is sent
+     in a port-destroyed notification to the backup port.  If there is
+     no registered port-destroyed request, remaining messages queued to
+     the port are destroyed and extant send and send-once rights turn
+     into dead names.  If those send and send-once rights have
+     dead-name requests registered, then dead-name notifications are
+     generated for them.
+
+     If NAME denotes a send-once right, then the send-once right is
+     used to produce a send-once notification for the port.
+
+     If NAME denotes a send-once, send, and/or receive right, and it
+     has a dead-name request registered, then the registered send-once
+     right is used to produce a port-deleted notification for the name.
+
+     The function returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_NAME' if
+     NAME did not denote a right.
+
+     The `mach_port_destroy' call is actually an RPC to TASK, normally
+     a send right for a task port, but potentially any send right.  In
+     addition to the normal diagnostic return codes from the call's
+     server (normally the kernel), the call may return `mach_msg'
+     return codes.
+
+
+File: mach.info,  Node: Port Names,  Next: Port Rights,  Prev: Port Destruction,  Up: Port Manipulation Interface
+
+4.3.3 Port Names
+----------------
+
+ -- Function: kern_return_t mach_port_names (ipc_space_t TASK,
+          mach_port_array_t *NAMES, mach_msg_type_number_t *NCOUNT,
+          mach_port_type_array_t *TYPES, mach_msg_type_number_t *TCOUNT)
+     The function `mach_port_names' returns information about TASK's
+     port name space.  For each name, it also returns what type of
+     rights TASK holds.  (The same information returned by
+     `mach_port_type'.)  NAMES and TYPES are arrays that are
+     automatically allocated when the reply message is received. The
+     user should `vm_deallocate' them when the data is no longer needed.
+
+     `mach_port_names' will return in NAMES the names of the ports,
+     port sets, and dead names in the task's port name space, in no
+     particular order and in NCOUNT the number of names returned.  It
+     will return in TYPES the type of each corresponding name, which
+     indicates what kind of rights the task holds with that name.
+     TCOUNT should be the same as NCOUNT.
+
+     The function returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_TASK' if TASK was invalid, `KERN_RESOURCE_SHORTAGE'
+     if the kernel ran out of memory.
+
+     The `mach_port_names' call is actually an RPC to TASK, normally a
+     send right for a task port, but potentially any send right.  In
+     addition to the normal diagnostic return codes from the call's
+     server (normally the kernel), the call may return `mach_msg'
+     return codes.
+
+ -- Function: kern_return_t mach_port_type (ipc_space_t TASK,
+          mach_port_t NAME, mach_port_type_t *PTYPE)
+     The function `mach_port_type' returns information about TASK's
+     rights for a specific name in its port name space.  The returned
+     PTYPE is a bitmask indicating what rights TASK holds for the port,
+     port set or dead name.  The bitmask is composed of the following
+     bits:
+
+    `MACH_PORT_TYPE_SEND'
+          The name denotes a send right.
+
+    `MACH_PORT_TYPE_RECEIVE'
+          The name denotes a receive right.
+
+    `MACH_PORT_TYPE_SEND_ONCE'
+          The name denotes a send-once right.
+
+    `MACH_PORT_TYPE_PORT_SET'
+          The name denotes a port set.
+
+    `MACH_PORT_TYPE_DEAD_NAME'
+          The name is a dead name.
+
+    `MACH_PORT_TYPE_DNREQUEST'
+          A dead-name request has been registered for the right.
+
+    `MACH_PORT_TYPE_MAREQUEST'
+          A msg-accepted request for the right is pending.
+
+    `MACH_PORT_TYPE_COMPAT'
+          The port right was created in the compatibility mode.
+
+     The function returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_TASK' if TASK was invalid and `KERN_INVALID_NAME' if
+     NAME did not denote a right.
+
+     The `mach_port_type' call is actually an RPC to TASK, normally a
+     send right for a task port, but potentially any send right.  In
+     addition to the normal diagnostic return codes from the call's
+     server (normally the kernel), the call may return `mach_msg'
+     return codes.
+
+ -- Function: kern_return_t mach_port_rename (ipc_space_t TASK,
+          mach_port_t OLD_NAME, mach_port_t NEW_NAME)
+     The function `mach_port_rename' changes the name by which a port,
+     port set, or dead name is known to TASK.  OLD_NAME is the original
+     name and NEW_NAME the new name for the port right.  NEW_NAME must
+     not already be in use, and it can't be the distinguished values
+     `MACH_PORT_NULL' and `MACH_PORT_DEAD'.
+
+     The function returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_NAME' if
+     OLD_NAME did not denote a right, `KERN_INVALID_VALUE' if NEW_NAME
+     was `MACH_PORT_NULL' or `MACH_PORT_DEAD', `KERN_NAME_EXISTS' if
+     `new_name' already denoted a right and `KERN_RESOURCE_SHORTAGE' if
+     the kernel ran out of memory.
+
+     The `mach_port_rename' call is actually an RPC to TASK, normally a
+     send right for a task port, but potentially any send right.  In
+     addition to the normal diagnostic return codes from the call's
+     server (normally the kernel), the call may return `mach_msg'
+     return codes.
+
+
+File: mach.info,  Node: Port Rights,  Next: Ports and other Tasks,  Prev: Port Names,  Up: Port Manipulation Interface
+
+4.3.4 Port Rights
+-----------------
+
+ -- Function: kern_return_t mach_port_get_refs (ipc_space_t TASK,
+          mach_port_t NAME, mach_port_right_t RIGHT,
+          mach_port_urefs_t *REFS)
+     The function `mach_port_get_refs' returns the number of user
+     references a task has for a right.
+
+     The RIGHT argument takes the following values:
+        * `MACH_PORT_RIGHT_SEND'
+
+        * `MACH_PORT_RIGHT_RECEIVE'
+
+        * `MACH_PORT_RIGHT_SEND_ONCE'
+
+        * `MACH_PORT_RIGHT_PORT_SET'
+
+        * `MACH_PORT_RIGHT_DEAD_NAME'
+
+     If NAME denotes a right, but not the type of right specified, then
+     zero is returned.  Otherwise a positive number of user references
+     is returned.  Note that a name may simultaneously denote send and
+     receive rights.
+
+     The function returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_VALUE' if
+     RIGHT was invalid and `KERN_INVALID_NAME' if NAME did not denote a
+     right.
+
+     The `mach_port_get_refs' call is actually an RPC to TASK, normally
+     a send right for a task port, but potentially any send right.  In
+     addition to the normal diagnostic return codes from the call's
+     server (normally the kernel), the call may return `mach_msg'
+     return codes.
+
+ -- Function: kern_return_t mach_port_mod_refs (ipc_space_t TASK,
+          mach_port_t NAME, mach_port_right_t RIGHT,
+          mach_port_delta_t DELTA)
+     The function `mach_port_mod_refs' requests that the number of user
+     references a task has for a right be changed.  This results in the
+     right being destroyed, if the number of user references is changed
+     to zero.  The task holding the right is TASK, NAME should denote
+     the specified right.  RIGHT denotes the type of right being
+     modified.  DELTA is the signed change to the number of user
+     references.
+
+     The RIGHT argument takes the following values:
+        * `MACH_PORT_RIGHT_SEND'
+
+        * `MACH_PORT_RIGHT_RECEIVE'
+
+        * `MACH_PORT_RIGHT_SEND_ONCE'
+
+        * `MACH_PORT_RIGHT_PORT_SET'
+
+        * `MACH_PORT_RIGHT_DEAD_NAME'
+
+     The number of user references for the right is changed by the
+     amount DELTA, subject to the following restrictions: port sets,
+     receive rights, and send-once rights may only have one user
+     reference.  The resulting number of user references can't be
+     negative.  If the resulting number of user references is zero, the
+     effect is to deallocate the right.  For dead names and send
+     rights, there is an implementation-defined maximum number of user
+     references.
+
+     If the call destroys the right, then the effect is as described for
+     `mach_port_destroy', with the exception that `mach_port_destroy'
+     simultaneously destroys all the rights denoted by a name, while
+     `mach_port_mod_refs' can only destroy one right.  The name will be
+     available for reuse if it only denoted the one right.
+
+     The function returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_VALUE' if
+     RIGHT was invalid or the user-reference count would become
+     negative, `KERN_INVALID_NAME' if NAME did not denote a right,
+     `KERN_INVALID_RIGHT' if NAME denoted a right, but not the
+     specified right and `KERN_UREFS_OVERFLOW' if the user-reference
+     count would overflow.
+
+     The `mach_port_mod_refs' call is actually an RPC to TASK, normally
+     a send right for a task port, but potentially any send right.  In
+     addition to the normal diagnostic return codes from the call's
+     server (normally the kernel), the call may return `mach_msg'
+     return codes.
+
+
+File: mach.info,  Node: Ports and other Tasks,  Next: Receive Rights,  Prev: Port Rights,  Up: Port Manipulation Interface
+
+4.3.5 Ports and other Tasks
+---------------------------
+
+ -- Function: kern_return_t mach_port_insert_right (ipc_space_t TASK,
+          mach_port_t NAME, mach_port_t RIGHT,
+          mach_msg_type_name_t RIGHT_TYPE)
+     The function MACH_PORT_INSERT_RIGHT inserts into TASK the caller's
+     right for a port, using a specified name for the right in the
+     target task.
+
+     The specified NAME can't be one of the reserved values
+     `MACH_PORT_NULL' or `MACH_PORT_DEAD'.  The RIGHT can't be
+     `MACH_PORT_NULL' or `MACH_PORT_DEAD'.
+
+     The argument RIGHT_TYPE specifies a right to be inserted and how
+     that right should be extracted from the caller.  It should be a
+     value appropriate for MSGT_NAME; see `mach_msg'.  If RIGHT_TYPE is
+     `MACH_MSG_TYPE_MAKE_SEND', `MACH_MSG_TYPE_MOVE_SEND', or
+     `MACH_MSG_TYPE_COPY_SEND', then a send right is inserted.  If the
+     target already holds send or receive rights for the port, then
+     NAME should denote those rights in the target.  Otherwise, NAME
+     should be unused in the target.  If the target already has send
+     rights, then those send rights gain an additional user reference.
+     Otherwise, the target gains a send right, with a user reference
+     count of one.
+
+     If RIGHT_TYPE is `MACH_MSG_TYPE_MAKE_SEND_ONCE' or
+     `MACH_MSG_TYPE_MOVE_SEND_ONCE', then a send-once right is inserted.
+     The name should be unused in the target.  The target gains a
+     send-once right.
+
+     If RIGHT_TYPE is `MACH_MSG_TYPE_MOVE_RECEIVE', then a receive
+     right is inserted.  If the target already holds send rights for the
+     port, then name should denote those rights in the target.
+     Otherwise, name should be unused in the target.  The receive right
+     is moved into the target task.
+
+     The function returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_VALUE' if
+     RIGHT was not a port right or NAME was `MACH_PORT_NULL' or
+     `MACH_PORT_DEAD', `KERN_NAME_EXISTS' if NAME already denoted a
+     right, `KERN_INVALID_CAPABILITY' if RIGHT was `MACH_PORT_NULL' or
+     `MACH_PORT_DEAD' `KERN_RIGHT_EXISTS' if TASK already had rights
+     for the port, with a different name, `KERN_UREFS_OVERFLOW' if the
+     user-reference count would overflow and `KERN_RESOURCE_SHORTAGE'
+     if the kernel ran out of memory.
+
+     The `mach_port_insert_right' call is actually an RPC to TASK,
+     normally a send right for a task port, but potentially any send
+     right.  In addition to the normal diagnostic return codes from the
+     call's server (normally the kernel), the call may return
+     `mach_msg' return codes.
+
+ -- Function: kern_return_t mach_port_extract_right (ipc_space_t TASK,
+          mach_port_t NAME, mach_msg_type_name_t DESIRED_TYPE,
+          mach_port_t *RIGHT, mach_msg_type_name_t *ACQUIRED_TYPE)
+     The function MACH_PORT_EXTRACT_RIGHT extracts a port right from
+     the target TASK and returns it to the caller as if the task sent
+     the right voluntarily, using DESIRED_TYPE as the value of
+     MSGT_NAME.  *Note Mach Message Call::.
+
+     The returned value of ACQUIRED_TYPE will be
+     `MACH_MSG_TYPE_PORT_SEND' if a send right is extracted,
+     `MACH_MSG_TYPE_PORT_RECEIVE' if a receive right is extracted, and
+     `MACH_MSG_TYPE_PORT_SEND_ONCE' if a send-once right is extracted.
+
+     The function returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_NAME' if
+     NAME did not denote a right, `KERN_INVALID_RIGHT' if NAME denoted
+     a right, but an invalid one, `KERN_INVALID_VALUE' if DESIRED_TYPE
+     was invalid.
+
+     The `mach_port_extract_right' call is actually an RPC to TASK,
+     normally a send right for a task port, but potentially any send
+     right.  In addition to the normal diagnostic return codes from the
+     call's server (normally the kernel), the call may return `mach_msg'
+     return codes.
+
+
+File: mach.info,  Node: Receive Rights,  Next: Port Sets,  Prev: Ports and other Tasks,  Up: Port Manipulation Interface
+
+4.3.6 Receive Rights
+--------------------
+
+ -- Data type: mach_port_seqno_t
+     The `mach_port_seqno_t' data type is an `unsigned int' which
+     contains the sequence number of a port.
+
+ -- Data type: mach_port_mscount_t
+     The `mach_port_mscount_t' data type is an `unsigned int' which
+     contains the make-send count for a port.
+
+ -- Data type: mach_port_msgcount_t
+     The `mach_port_msgcount_t' data type is an `unsigned int' which
+     contains a number of messages.
+
+ -- Data type: mach_port_rights_t
+     The `mach_port_rights_t' data type is an `unsigned int' which
+     contains a number of rights for a port.
+
+ -- Data type: mach_port_status_t
+     This structure contains some status information about a port,
+     which can be queried with `mach_port_get_receive_status'.  It has
+     the following members:
+
+    `mach_port_t mps_pset'
+          The containing port set.
+
+    `mach_port_seqno_t mps_seqno'
+          The sequence number.
+
+    `mach_port_mscount_t mps_mscount'
+          The make-send count.
+
+    `mach_port_msgcount_t mps_qlimit'
+          The maximum number of messages in the queue.
+
+    `mach_port_msgcount_t mps_msgcount'
+          The current number of messages in the queue.
+
+    `mach_port_rights_t mps_sorights'
+          The number of send-once rights that exist.
+
+    `boolean_t mps_srights'
+          `TRUE' if send rights exist.
+
+    `boolean_t mps_pdrequest'
+          `TRUE' if port-deleted notification is requested.
+
+    `boolean_t mps_nsrequest'
+          `TRUE' if no-senders notification is requested.
+
+ -- Function: kern_return_t mach_port_get_receive_status
+          (ipc_space_t TASK, mach_port_t NAME,
+          mach_port_status_t *STATUS)
+     The function `mach_port_get_receive_status' returns the current
+     status of the specified receive right.
+
+     The function returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_NAME' if
+     NAME did not denote a right and `KERN_INVALID_RIGHT' if NAME
+     denoted a right, but not a receive right.
+
+     The `mach_port_get_receive_status' call is actually an RPC to TASK,
+     normally a send right for a task port, but potentially any send
+     right.  In addition to the normal diagnostic return codes from the
+     call's server (normally the kernel), the call may return
+     `mach_msg' return codes.
+
+ -- Function: kern_return_t mach_port_set_mscount (ipc_space_t TASK,
+          mach_port_t NAME, mach_port_mscount_t MSCOUNT)
+     The function `mach_port_set_mscount' changes the make-send count of
+     TASK's receive right named NAME to MSCOUNT.  All values for
+     MSCOUNT are valid.
+
+     The function returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_NAME' if
+     NAME did not denote a right and `KERN_INVALID_RIGHT' if NAME
+     denoted a right, but not a receive right.
+
+     The `mach_port_set_mscount' call is actually an RPC to TASK,
+     normally a send right for a task port, but potentially any send
+     right.  In addition to the normal diagnostic return codes from the
+     call's server (normally the kernel), the call may return
+     `mach_msg' return codes.
+
+ -- Function: kern_return_t mach_port_set_qlimit (ipc_space_t TASK,
+          mach_port_t NAME, mach_port_msgcount_t QLIMIT)
+     The function `mach_port_set_qlimit' changes the queue limit TASK's
+     receive right named NAME to QLIMIT.  Valid values for QLIMIT are
+     between zero and `MACH_PORT_QLIMIT_MAX', inclusive.
+
+     The function returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_NAME' if
+     NAME did not denote a right, `KERN_INVALID_RIGHT' if NAME denoted
+     a right, but not a receive right and `KERN_INVALID_VALUE' if
+     QLIMIT was invalid.
+
+     The `mach_port_set_qlimit' call is actually an RPC to TASK,
+     normally a send right for a task port, but potentially any send
+     right.  In addition to the normal diagnostic return codes from the
+     call's server (normally the kernel), the call may return
+     `mach_msg' return codes.
+
+ -- Function: kern_return_t mach_port_set_seqno (ipc_space_t TASK,
+          mach_port_t NAME, mach_port_seqno_t SEQNO)
+     The function `mach_port_set_seqno' changes the sequence number
+     TASK's receive right named NAME to SEQNO.  All sequence number
+     values are valid.  The next message received from the port will be
+     stamped with the specified sequence number.
+
+     The function returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_NAME' if
+     NAME did not denote a right and `KERN_INVALID_RIGHT' if NAME
+     denoted a right, but not a receive right.
+
+     The `mach_port_set_seqno' call is actually an RPC to TASK,
+     normally a send right for a task port, but potentially any send
+     right.  In addition to the normal diagnostic return codes from the
+     call's server (normally the kernel), the call may return
+     `mach_msg' return codes.
+
+
+File: mach.info,  Node: Port Sets,  Next: Request Notifications,  Prev: Receive Rights,  Up: Port Manipulation Interface
+
+4.3.7 Port Sets
+---------------
+
+ -- Function: kern_return_t mach_port_get_set_status (ipc_space_t TASK,
+          mach_port_t NAME, mach_port_array_t *MEMBERS,
+          mach_msg_type_number_t *COUNT)
+     The function `mach_port_get_set_status' returns the members of a
+     port set.  MEMBERS is an array that is automatically allocated
+     when the reply message is received.  The user should
+     `vm_deallocate' it when the data is no longer needed.
+
+     The function returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_NAME' if
+     NAME did not denote a right, `KERN_INVALID_RIGHT' if NAME denoted
+     a right, but not a receive right and `KERN_RESOURCE_SHORTAGE' if
+     the kernel ran out of memory.
+
+     The `mach_port_get_set_status' call is actually an RPC to TASK,
+     normally a send right for a task port, but potentially any send
+     right.  In addition to the normal diagnostic return codes from the
+     call's server (normally the kernel), the call may return `mach_msg'
+     return codes.
+
+ -- Function: kern_return_t mach_port_move_member (ipc_space_t TASK,
+          mach_port_t MEMBER, mach_port_t AFTER)
+     The function MACH_PORT_MOVE_MEMBER moves the receive right MEMBER
+     into the port set AFTER.  If the receive right is already a member
+     of another port set, it is removed from that set first (the whole
+     operation is atomic).  If the port set is `MACH_PORT_NULL', then
+     the receive right is not put into a port set, but removed from its
+     current port set.
+
+     The function returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_NAME' if
+     MEMBER or AFTER did not denote a right, `KERN_INVALID_RIGHT' if
+     MEMBER denoted a right, but not a receive right or AFTER denoted a
+     right, but not a port set, and `KERN_NOT_IN_SET' if AFTER was
+     `MACH_PORT_NULL', but `member' wasn't currently in a port set.
+
+     The `mach_port_move_member' call is actually an RPC to TASK,
+     normally a send right for a task port, but potentially any send
+     right.  In addition to the normal diagnostic return codes from the
+     call's server (normally the kernel), the call may return
+     `mach_msg' return codes.
+
+
+File: mach.info,  Node: Request Notifications,  Prev: Port Sets,  Up: Port Manipulation Interface
+
+4.3.8 Request Notifications
+---------------------------
+
+ -- Function: kern_return_t mach_port_request_notification
+          (ipc_space_t TASK, mach_port_t NAME, mach_msg_id_t VARIANT,
+          mach_port_mscount_t SYNC, mach_port_t NOTIFY,
+          mach_msg_type_name_t NOTIFY_TYPE, mach_port_t *PREVIOUS)
+     The function `mach_port_request_notification' registers a request
+     for a notification and supplies the send-once right NOTIFY to
+     which the notification will be sent.  The NOTIFY_TYPE denotes the
+     IPC type for the send-once right, which can be
+     `MACH_MSG_TYPE_MAKE_SEND_ONCE' or `MACH_MSG_TYPE_MOVE_SEND_ONCE'.
+     It is an atomic swap, returning the previously registered
+     send-once right (or `MACH_PORT_NULL' for none) in PREVIOUS.  A
+     previous notification request may be cancelled by providing
+     `MACH_PORT_NULL' for NOTIFY.
+
+     The VARIANT argument takes the following values:
+
+    `MACH_NOTIFY_PORT_DESTROYED'
+          SYNC must be zero.  The NAME must specify a receive right,
+          and the call requests a port-destroyed notification for the
+          receive right.  If the receive right were to have been
+          destroyed, say by `mach_port_destroy', then instead the
+          receive right will be sent in a port-destroyed notification
+          to the registered send-once right.
+
+    `MACH_NOTIFY_DEAD_NAME'
+          The call requests a dead-name notification.  NAME specifies
+          send, receive, or send-once rights for a port.  If the port
+          is destroyed (and the right remains, becoming a dead name),
+          then a dead-name notification which carries the name of the
+          right will be sent to the registered send-once right.  If
+          NOTIFY is not null and sync is non-zero, the name may specify
+          a dead name, and a dead-name notification is immediately
+          generated.
+
+          Whenever a dead-name notification is generated, the user
+          reference count of the dead name is incremented.  For
+          example, a send right with two user refs has a registered
+          dead-name request.  If the port is destroyed, the send right
+          turns into a dead name with three user refs (instead of two),
+          and a dead-name notification is generated.
+
+          If the name is made available for reuse, perhaps because of
+          `mach_port_destroy' or `mach_port_mod_refs', or the name
+          denotes a send-once right which has a message sent to it,
+          then the registered send-once right is used to generate a
+          port-deleted notification.
+
+    `MACH_NOTIFY_NO_SENDERS'
+          The call requests a no-senders notification.  NAME must
+          specify a receive right.  If NOTIFY is not null, and the
+          receive right's make-send count is greater than or equal to
+          the sync value, and it has no extant send rights, than an
+          immediate no-senders notification is generated.  Otherwise
+          the notification is generated when the receive right next
+          loses its last extant send right.  In either case, any
+          previously registered send-once right is returned.
+
+          The no-senders notification carries the value the port's
+          make-send count had when it was generated.  The make-send
+          count is incremented whenever `MACH_MSG_TYPE_MAKE_SEND' is
+          used to create a new send right from the receive right.  The
+          make-send count is reset to zero when the receive right is
+          carried in a message.
+
+     The function returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_TASK' if TASK was invalid, `KERN_INVALID_VALUE' if
+     VARIANT was invalid, `KERN_INVALID_NAME' if NAME did not denote a
+     right, `KERN_INVALID_RIGHT' if NAME denoted an invalid right and
+     `KERN_INVALID_CAPABILITY' if NOTIFY was invalid.
+
+     When using `MACH_NOTIFY_PORT_DESTROYED', the function returns
+     `KERN_INVALID_VALUE' if SYNC wasn't zero.
+
+     When using `MACH_NOTIFY_DEAD_NAME', the function returns
+     `KERN_RESOURCE_SHORTAGE' if the kernel ran out of memory,
+     `KERN_INVALID_ARGUMENT' if NAME denotes a dead name, but SYNC is
+     zero or NOTIFY is `MACH_PORT_NULL', and `KERN_UREFS_OVERFLOW' if
+     NAME denotes a dead name, but generating an immediate dead-name
+     notification would overflow the name's user-reference count.
+
+     The `mach_port_request_notification' call is actually an RPC to
+     TASK, normally a send right for a task port, but potentially any
+     send right.  In addition to the normal diagnostic return codes
+     from the call's server (normally the kernel), the call may return
+     `mach_msg' return codes.
+
+
+File: mach.info,  Node: Virtual Memory Interface,  Next: External Memory Management,  Prev: Inter Process Communication,  Up: Top
+
+5 Virtual Memory Interface
+**************************
+
+ -- Data type: vm_task_t
+     This is a `task_t' (and as such a `mach_port_t'), which holds a
+     port name associated with a port that represents a virtual memory
+     map in the kernel.  An virtual memory map is used by the kernel to
+     manage the address space of a task.  The virtual memory map
+     doesn't get a port name of its own.  Instead the port name of the
+     task provided with the virtual memory is used to name the virtual
+     memory map of the task (as is indicated by the fact that the type
+     of `vm_task_t' is actually `task_t').
+
+     The virtual memory maps of tasks are the only ones accessible
+     outside of the kernel.
+
+* Menu:
+
+* Memory Allocation::             Allocation of new virtual memory.
+* Memory Deallocation::           Freeing unused virtual memory.
+* Data Transfer::                 Reading, writing and copying memory.
+* Memory Attributes::             Tweaking memory regions.
+* Mapping Memory Objects::        How to map memory objects.
+* Memory Statistics::             How to get statistics about memory usage.
+
+
+File: mach.info,  Node: Memory Allocation,  Next: Memory Deallocation,  Up: Virtual Memory Interface
+
+5.1 Memory Allocation
+=====================
+
+ -- Function: kern_return_t vm_allocate (vm_task_t TARGET_TASK,
+          vm_address_t *ADDRESS, vm_size_t SIZE, boolean_t ANYWHERE)
+     The function `vm_allocate' allocates a region of virtual memory,
+     placing it in the specified TASK's address space.
+
+     The starting address is ADDRESS.  If the ANYWHERE option is false,
+     an attempt is made to allocate virtual memory starting at this
+     virtual address.  If this address is not at the beginning of a
+     virtual page, it will be rounded down to one.  If there is not
+     enough space at this address, no memory will be allocated.  If the
+     ANYWHERE option is true, the input value of this address will be
+     ignored, and the space will be allocated wherever it is available.
+     In either case, the address at which memory was actually
+     allocated will be returned in ADDRESS.
+
+     SIZE is the number of bytes to allocate (rounded by the system in
+     a machine dependent way to an integral number of virtual pages).
+
+     If ANYWHERE is true, the kernel should find and allocate any
+     region of the specified size, and return the address of the
+     resulting region in address address, rounded to a virtual page
+     boundary if there is sufficient space.
+
+     The physical memory is not actually allocated until the new virtual
+     memory is referenced.  By default, the kernel rounds all addresses
+     down to the nearest page boundary and all memory sizes up to the
+     nearest page size.  The global variable `vm_page_size' contains
+     the page size.  `mach_task_self' returns the value of the current
+     task port which should be used as the TARGET_TASK argument in
+     order to allocate memory in the caller's address space.  For
+     languages other than C, these values can be obtained by the calls
+     `vm_statistics' and `mach_task_self'.  Initially, the pages of
+     allocated memory will be protected to allow all forms of access,
+     and will be inherited in child tasks as a copy.  Subsequent calls
+     to `vm_protect' and `vm_inherit' may be used to change these
+     properties.  The allocated region is always zero-filled.
+
+     The function returns `KERN_SUCCESS' if the memory was successfully
+     allocated, `KERN_INVALID_ADDRESS' if an invalid address was
+     specified and `KERN_NO_SPACE' if there was not enough space left to
+     satisfy the request.
+
+
+File: mach.info,  Node: Memory Deallocation,  Next: Data Transfer,  Prev: Memory Allocation,  Up: Virtual Memory Interface
+
+5.2 Memory Deallocation
+=======================
+
+ -- Function: kern_return_t vm_deallocate (vm_task_t TARGET_TASK,
+          vm_address_t ADDRESS, vm_size_t SIZE)
+     `vm_deallocate' relinquishes access to a region of a TASK's
+     address space, causing further access to that memory to fail.  This
+     address range will be available for reallocation.  ADDRESS is the
+     starting address, which will be rounded down to a page boundary.
+     SIZE is the number of bytes to deallocate, which will be rounded
+     up to give a page boundary.  Note, that because of the rounding to
+     virtual page boundaries, more than SIZE bytes may be deallocated.
+     Use `vm_page_size' or `vm_statistics' to find out the current
+     virtual page size.
+
+     This call may be used to deallocte memory that was passed to a
+     task in a message (via out of line data).  In that case, the
+     rounding should cause no trouble, since the region of memory was
+     allocated as a set of pages.
+
+     The `vm_deallocate' call affects only the task specified by the
+     TARGET_TASK.  Other tasks which may have access to this memory may
+     continue to reference it.
+
+     The function returns `KERN_SUCCESS' if the memory was successfully
+     deallocated and `KERN_INVALID_ADDRESS' if an invalid or
+     non-allocated address was specified.
+
+
+File: mach.info,  Node: Data Transfer,  Next: Memory Attributes,  Prev: Memory Deallocation,  Up: Virtual Memory Interface
+
+5.3 Data Transfer
+=================
+
+ -- Function: kern_return_t vm_read (vm_task_t TARGET_TASK,
+          vm_address_t ADDRESS, vm_size_t SIZE, vm_offset_t *DATA,
+          mach_msg_type_number_t *DATA_COUNT)
+     The function `vm_read' allows one task's virtual memory to be read
+     by another task.  The TARGET_TASK is the task whose memory is to
+     be read.  ADDRESS is the first address to be read and must be on a
+     page boundary.  SIZE is the number of bytes of data to be read and
+     must be an integral number of pages.  DATA is the array of data
+     copied from the given task, and DATA_COUNT is the size of the data
+     array in bytes (will be an integral number of pages).
+
+     Note that the data array is returned in a newly allocated region;
+     the task reading the data should `vm_deallocate' this region when
+     it is done with the data.
+
+     The function returns `KERN_SUCCESS' if the memory was successfully
+     read, `KERN_INVALID_ADDRESS' if an invalid or non-allocated address
+     was specified or there was not SIZE bytes of data following the
+     address, `KERN_INVALID_ARGUMENT' if the address does not start on a
+     page boundary or the size is not an integral number of pages,
+     `KERN_PROTECTION_FAILURE' if the address region in the target task
+     is protected against reading and `KERN_NO_SPACE' if there was not
+     enough room in the callers virtual memory to allocate space for
+     the data to be returned.
+
+ -- Function: kern_return_t vm_write (vm_task_t TARGET_TASK,
+          vm_address_t ADDRESS, vm_offset_t DATA,
+          mach_msg_type_number_t DATA_COUNT)
+     The function `vm_write' allows a task to write to the vrtual memory
+     of TARGET_TASK.  ADDRESS is the starting address in task to be
+     affected.  DATA is an array of bytes to be written, and DATA_COUNT
+     the size of the DATA array.
+
+     The current implementation requires that ADDRESS, DATA and
+     DATA_COUNT all be page-aligned.  Otherwise,
+     `KERN_INVALID_ARGUMENT' is returned.
+
+     The function returns `KERN_SUCCESS' if the memory was successfully
+     written, `KERN_INVALID_ADDRESS' if an invalid or non-allocated
+     address was specified or there was not DATA_COUNT bytes of
+     allocated memory starting at ADDRESS and `KERN_PROTECTION_FAILURE'
+     if the address region in the target task is protected against
+     writing.
+
+ -- Function: kern_return_t vm_copy (vm_task_t TARGET_TASK,
+          vm_address_t SOURCE_ADDRESS, vm_size_t COUNT,
+          vm_offset_t DEST_ADDRESS)
+     The function `vm_copy' causes the source memory range to be copied
+     to the destination address.  The source and destination memory
+     ranges may overlap.  The destination address range must already be
+     allocated and writable; the source range must be readable.
+
+     `vm_copy' is equivalent to `vm_read' followed by `vm_write'.
+
+     The current implementation requires that ADDRESS, DATA and
+     DATA_COUNT all be page-aligned.  Otherwise,
+     `KERN_INVALID_ARGUMENT' is returned.
+
+     The function returns `KERN_SUCCESS' if the memory was successfully
+     written, `KERN_INVALID_ADDRESS' if an invalid or non-allocated
+     address was specified or there was insufficient memory allocated
+     at one of the addresses and `KERN_PROTECTION_FAILURE' if the
+     destination region was not writable or the source region was not
+     readable.
+
+
+File: mach.info,  Node: Memory Attributes,  Next: Mapping Memory Objects,  Prev: Data Transfer,  Up: Virtual Memory Interface
+
+5.4 Memory Attributes
+=====================
+
+ -- Function: kern_return_t vm_region (vm_task_t TARGET_TASK,
+          vm_address_t *ADDRESS, vm_size_t *SIZE,
+          vm_prot_t *PROTECTION, vm_prot_t *MAX_PROTECTION,
+          vm_inherit_t *INHERITANCE, boolean_t *SHARED,
+          memory_object_name_t *OBJECT_NAME, vm_offset_t *OFFSET)
+     The function `vm_region' returns a description of the specified
+     region of TARGET_TASK's virtual address space.  `vm_region' begins
+     at ADDRESS and looks forward through memory until it comes to an
+     allocated region.  If address is within a region, then that region
+     is used.  Various bits of information about the region are
+     returned.  If ADDRESS was not within a region, then ADDRESS is set
+     to the start of the first region which follows the incoming value.
+     In this way an entire address space can be scanned.
+
+     The SIZE returned is the size of the located region in bytes.
+     PROTECTION is the current protection of the region, MAX_PROTECTION
+     is the maximum allowable protection for this region.  INHERITANCE
+     is the inheritance attribute for this region.  SHARED tells if the
+     region is shared or not.  The port OBJECT_NAME identifies the
+     memory object associated with this region, and OFFSET is the
+     offset into the pager object that this region begins at.
+
+     The function returns `KERN_SUCCESS' if the memory region was
+     successfully located and the information returned and
+     `KERN_NO_SPACE' if there is no region at or above ADDRESS in the
+     specified task.
+
+ -- Function: kern_return_t vm_protect (vm_task_t TARGET_TASK,
+          vm_address_t ADDRESS, vm_size_t SIZE, boolean_t SET_MAXIMUM,
+          vm_prot_t NEW_PROTECTION)
+     The function `vm_protect' sets the virtual memory access privileges
+     for a range of allocated addresses in TARGET_TASK's virtual
+     address space.  The protection argument describes a combination of
+     read, write, and execute accesses that should be _permitted_.
+
+     ADDRESS is the starting address, which will be rounded down to a
+     page boundary.  SIZE is the size in bytes of the region for which
+     protection is to change, and will be rounded up to give a page
+     boundary.  If SET_MAXIMUM is set, make the protection change apply
+     to the maximum protection associated with this address range;
+     otherwise, the current protection on this range is changed.  If
+     the maximum protection is reduced below the current protection,
+     both will be changed to reflect the new maximum.  NEW_PROTECTION
+     is the new protection value for this region; a set of:
+     `VM_PROT_READ', `VM_PROT_WRITE', `VM_PROT_EXECUTE'.
+
+     The enforcement of virtual memory protection is machine-dependent.
+     Nominally read access requires `VM_PROT_READ' permission, write
+     access requires `VM_PROT_WRITE' permission, and execute access
+     requires `VM_PROT_EXECUTE' permission.  However, some combinations
+     of access rights may not be supported.  In particular, the kernel
+     interface allows write access to require `VM_PROT_READ' and
+     `VM_PROT_WRITE' permission and execute access to require
+     `VM_PROT_READ' permission.
+
+     The function returns `KERN_SUCCESS' if the memory was successfully
+     protected, `KERN_INVALID_ADDRESS' if an invalid or non-allocated
+     address was specified and `KERN_PROTECTION_FAILURE' if an attempt
+     was made to increase the current or maximum protection beyond the
+     existing maximum protection value.
+
+ -- Function: kern_return_t vm_inherit (vm_task_t TARGET_TASK,
+          vm_address_t ADDRESS, vm_size_t SIZE,
+          vm_inherit_t NEW_INHERITANCE)
+     The function `vm_inherit' specifies how a region of TARGET_TASK's
+     address space is to be passed to child tasks at the time of task
+     creation.  Inheritance is an attribute of virtual pages, so
+     ADDRESS to start from will be rounded down to a page boundary and
+     SIZE, the size in bytes of the region for wihch inheritance is to
+     change, will be rounded up to give a page boundary.  How this
+     memory is to be inherited in child tasks is specified by
+     NEW_INHERITANCE.  Inheritance is specified by using one of these
+     following three values:
+
+    `VM_INHERIT_SHARE'
+          Child tasks will share this memory with this task.
+
+    `VM_INHERIT_COPY'
+          Child tasks will receive a copy of this region.
+
+    `VM_INHERIT_NONE'
+          This region will be absent from child tasks.
+
+     Setting `vm_inherit' to `VM_INHERIT_SHARE' and forking a child
+     task is the only way two Mach tasks can share physical memory.
+     Remember that all the theads of a given task share all the same
+     memory.
+
+     The function returns `KERN_SUCCESS' if the memory inheritance was
+     successfully set and `KERN_INVALID_ADDRESS' if an invalid or
+     non-allocated address was specified.
+
+ -- Function: kern_return_t vm_wire (host_priv_t HOST_PRIV,
+          vm_task_t TARGET_TASK, vm_address_t ADDRESS, vm_size_t SIZE,
+          vm_prot_t ACCESS)
+     The function `vm_wire' allows privileged applications to control
+     memory pageability.  HOST_PRIV is the privileged host port for the
+     host on which TARGET_TASK resides.  ADDRESS is the starting
+     address, which will be rounded down to a page boundary.  SIZE is
+     the size in bytes of the region for which protection is to change,
+     and will be rounded up to give a page boundary.  ACCESS specifies
+     the types of accesses that must not cause page faults.
+
+     The semantics of a successful `vm_wire' operation are that memory
+     in the specified range will not cause page faults for any accesses
+     included in access.  Data memory can be made non-pageable (wired)
+     with a access argument of `VM_PROT_READ | VM_PROT_WRITE'.  A
+     special case is that `VM_PROT_NONE' makes the memory pageable.
+
+     The function returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_HOST' if HOST_PRIV was not the privileged host port,
+     `KERN_INVALID_TASK' if TASK was not a valid task,
+     `KERN_INVALID_VALUE' if ACCESS specified an invalid access mode,
+     `KERN_FAILURE' if some memory in the specified range is not
+     present or has an inappropriate protection value, and
+     `KERN_INVALID_ARGUMENT' if unwiring (ACCESS is `VM_PROT_NONE') and
+     the memory is not already wired.
+
+     The `vm_wire' call is actually an RPC to HOST_PRIV, normally a
+     send right for a privileged host port, but potentially any send
+     right.  In addition to the normal diagnostic return codes from the
+     call's server (normally the kernel), the call may return
+     `mach_msg' return codes.
+
+ -- Function: kern_return_t vm_machine_attribute (vm_task_t TASK,
+          vm_address_t ADDRESS, vm_size_t SIZE, vm_prot_t ACCESS,
+          vm_machine_attribute_t ATTRIBUTE,
+          vm_machine_attribute_val_t VALUE)
+     The function `vm_machine_attribute' specifies machine-specific
+     attributes for a VM mapping, such as cachability, migrability,
+     replicability.  This is used on machines that allow the user
+     control over the cache (this is the case for MIPS architectures)
+     or placement of memory pages as in NUMA architectures (Non-Uniform
+     Memory Access time) such as the IBM ACE multiprocessor.
+
+     Machine-specific attributes can be consider additions to the
+     machine-independent ones such as protection and inheritance, but
+     they are not guaranteed to be supported by any given machine.
+     Moreover, implementations of Mach on new architectures might find
+     the need for new attribute types and or values besides the ones
+     defined in the initial implementation.
+
+     The types currently defined are
+    `MATTR_CACHE'
+          Controls caching of memory pages
+
+    `MATTR_MIGRATE'
+          Controls migrability of memory pages
+
+    `MATTR_REPLICATE'
+          Controls replication of memory pages
+
+     Corresponding values, and meaning of a specific call to
+     `vm_machine_attribute'
+    `MATTR_VAL_ON'
+          Enables the attribute.  Being enabled is the default value
+          for any applicable attribute.
+
+    `MATTR_VAL_OFF'
+          Disables the attribute, making memory non-cached, or
+          non-migratable, or non-replicatable.
+
+    `MATTR_VAL_GET'
+          Returns the current value of the attribute for the memory
+          segment.  If the attribute does not apply uniformly to the
+          given range the value returned applies to the initial portion
+          of the segment only.
+
+    `MATTR_VAL_CACHE_FLUSH'
+          Flush the memory pages from the Cache.  The size value in
+          this case might be meaningful even if not a multiple of the
+          page size, depending on the implementation.
+
+    `MATTR_VAL_ICACHE_FLUSH'
+          Same as above, applied to the Instruction Cache alone.
+
+    `MATTR_VAL_DCACHE_FLUSH'
+          Same as above, applied to the Data Cache alone.
+
+     The function returns `KERN_SUCCESS' if call succeeded, and
+     `KERN_INVALID_ARGUMENT' if TASK is not a task, or ADDRESS and SIZE
+     do not define a valid address range in task, or ATTRIBUTE is not a
+     valid attribute type, or it is not implemented, or VALUE is not a
+     permissible value for attribute.
+
+
+File: mach.info,  Node: Mapping Memory Objects,  Next: Memory Statistics,  Prev: Memory Attributes,  Up: Virtual Memory Interface
+
+5.5 Mapping Memory Objects
+==========================
+
+ -- Function: kern_return_t vm_map (vm_task_t TARGET_TASK,
+          vm_address_t *ADDRESS, vm_size_t SIZE, vm_address_t MASK,
+          boolean_t ANYWHERE, memory_object_t MEMORY_OBJECT,
+          vm_offset_t OFFSET, boolean_t COPY, vm_prot_t CUR_PROTECTION,
+          vm_prot_t MAX_PROTECTION, vm_inherit_t INHERITANCE)
+     The function `vm_map' maps a region of virtual memory at the
+     specified address, for which data is to be supplied by the given
+     memory object, starting at the given offset within that object.
+     In addition to the arguments used in `vm_allocate', the `vm_map'
+     call allows the specification of an address alignment parameter,
+     and of the initial protection and inheritance values.
+
+     If the memory object in question is not currently in use, the
+     kernel will perform a `memory_object_init' call at this time.  If
+     the copy parameter is asserted, the specified region of the memory
+     object will be copied to this address space; changes made to this
+     object by other tasks will not be visible in this mapping, and
+     changes made in this mapping will not be visible to others (or
+     returned to the memory object).
+
+     The `vm_map' call returns once the mapping is established.
+     Completion of the call does not require any action on the part of
+     the memory manager.
+
+     Warning: Only memory objects that are provided by bona fide memory
+     managers should be used in the `vm_map' call.  A memory manager
+     must implement the memory object interface described elsewhere in
+     this manual.  If other ports are used, a thread that accesses the
+     mapped virtual memory may become permanently hung or may receive a
+     memory exception.
+
+     TARGET_TASK is the task to be affected.  The starting address is
+     ADDRESS.  If the ANYWHERE option is used, this address is ignored.
+     The address actually allocated will be returned in ADDRESS. SIZE
+     is the number of bytes to allocate (rounded by the system in a
+     machine dependent way).  The alignment restriction is specified by
+     MASK.  Bits asserted in this mask must not be asserted in the
+     address returned.  If ANYWHERE is set, the kernel should find and
+     allocate any region of the specified size, and return the address
+     of the resulting region in ADDRESS.
+
+     MEMORY_OBJECT is the port that represents the memory object: used
+     by user tasks in `vm_map'; used by the make requests for data or
+     other management actions.  If this port is `MEMORY_OBJECT_NULL',
+     then zero-filled memory is allocated instead.  Within a memory
+     object, OFFSET specifes an offset in bytes.  This must be page
+     aligned.  If COPY is set, the range of the memory object should be
+     copied to the target task, rather than mapped read-write.
+
+     The function returns `KERN_SUCCESS' if the object is mapped,
+     `KERN_NO_SPACE' if no unused region of the task's virtual address
+     space that meets the address, size, and alignment criteria could be
+     found, and `KERN_INVALID_ARGUMENT' if an invalid argument was
+     provided.
+
+
+File: mach.info,  Node: Memory Statistics,  Prev: Mapping Memory Objects,  Up: Virtual Memory Interface
+
+5.6 Memory Statistics
+=====================
+
+ -- Data type: vm_statistics_data_t
+     This structure is returned in VM_STATS by the `vm_statistics'
+     function and provides virtual memory statistics for the system.
+     It has the following members:
+
+    `long pagesize'
+          The page size in bytes.
+
+    `long free_count'
+          The number of free pages.
+
+    `long active_count'
+          The umber of active pages.
+
+    `long inactive_count'
+          The number of inactive pages.
+
+    `long wire_count'
+          The number of pages wired down.
+
+    `long zero_fill_count'
+          The number of zero filled pages.
+
+    `long reactivations'
+          The number of reactivated pages.
+
+    `long pageins'
+          The number of pageins.
+
+    `long pageouts'
+          The number of pageouts.
+
+    `long faults'
+          The number of faults.
+
+    `long cow_faults'
+          The number of copy-on-writes.
+
+    `long lookups'
+          The number of object cache lookups.
+
+    `long hits'
+          The number of object cache hits.
+
+ -- Function: kern_return_t vm_statistics (vm_task_t TARGET_TASK,
+          vm_statistics_data_t *VM_STATS)
+     The function `vm_statistics' returns the statistics about the
+     kernel's use of virtual memory since the kernel was booted.
+     `pagesize' can also be found as a global variable `vm_page_size'
+     which is set at task initialization and remains constant for the
+     life of the task.
+
+
+File: mach.info,  Node: External Memory Management,  Next: Threads and Tasks,  Prev: Virtual Memory Interface,  Up: Top
+
+6 External Memory Management
+****************************
+
+* Menu:
+
+* Memory Object Server::          The basics of external memory management.
+* Memory Object Creation::        How new memory objects are created.
+* Memory Object Termination::     How memory objects are terminated.
+* Memory Objects and Data::       Data transfer to and from memory objects.
+* Memory Object Locking::         How memory objects are locked.
+* Memory Object Attributes::      Manipulating attributes of memory objects.
+* Default Memory Manager::        Setting and using the default memory manager.
+
+
+File: mach.info,  Node: Memory Object Server,  Next: Memory Object Creation,  Up: External Memory Management
+
+6.1 Memory Object Server
+========================
+
+ -- Function: boolean_t memory_object_server (msg_header_t *IN_MSG,
+          msg_header_t *OUT_MSG)
+ -- Function: boolean_t memory_object_default_server
+          (msg_header_t *IN_MSG, msg_header_t *OUT_MSG)
+ -- Function: boolean_t seqnos_memory_object_server
+          (msg_header_t *IN_MSG, msg_header_t *OUT_MSG)
+ -- Function: boolean_t seqnos_memory_object_default_server
+          (msg_header_t *IN_MSG, msg_header_t *OUT_MSG)
+     A memory manager is a server task that responds to specific
+     messages from the kernel in order to handle memory management
+     functions for the kernel.
+
+     In order to isolate the memory manager from the specifics of
+     message formatting, the remote procedure call generator produces a
+     procedure, `memory_object_server', to handle a received message.
+     This function does all necessary argument handling, and actually
+     calls one of the following functions: `memory_object_init',
+     `memory_object_data_write', `memory_object_data_return',
+     `memory_object_data_request', `memory_object_data_unlock',
+     `memory_object_lock_completed', `memory_object_copy',
+     `memory_object_terminate'.  The *default memory manager* may get
+     two additional requests from the kernel: `memory_object_create'
+     and `memory_object_data_initialize'.  The remote procedure call
+     generator produces a procedure `memory_object_default_server' to
+     handle those functions specific to the default memory manager.
+
+     The `seqnos_memory_object_server' and
+     `seqnos_memory_object_default_server' differ from
+     `memory_object_server' and `memory_object_default_server' in that
+     they supply message sequence numbers to the server interfaces.
+     They call the `seqnos_memory_object_*' functions, which complement
+     the `memory_object_*' set of functions.
+
+     The return value from the `memory_object_server' function indicates
+     that the message was appropriate to the memory management interface
+     (returning `TRUE'), or that it could not handle this message
+     (returning `FALSE').
+
+     The IN_MSG argument is the message that has been received from the
+     kernel.  The OUT_MSG is a reply message, but this is not used for
+     this server.
+
+     The function returns `TRUE' to indicate that the message in
+     question was applicable to this interface, and that the appropriate
+     routine was called to interpret the message.  It returns `FALSE' to
+     indicate that the message did not apply to this interface, and
+     that no other action was taken.
+
+
+File: mach.info,  Node: Memory Object Creation,  Next: Memory Object Termination,  Prev: Memory Object Server,  Up: External Memory Management
+
+6.2 Memory Object Creation
+==========================
+
+ -- Function: kern_return_t memory_object_init
+          (memory_object_t MEMORY_OBJECT,
+          memory_object_control_t MEMORY_CONTROL,
+          memory_object_name_t MEMORY_OBJECT_NAME,
+          vm_size_t MEMORY_OBJECT_PAGE_SIZE)
+ -- Function: kern_return_t seqnos_memory_object_init
+          (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO,
+          memory_object_control_t MEMORY_CONTROL,
+          memory_object_name_t MEMORY_OBJECT_NAME,
+          vm_size_t MEMORY_OBJECT_PAGE_SIZE)
+     The function `memory_object_init' serves as a notification that the
+     kernel has been asked to map the given memory object into a task's
+     virtual address space.  Additionally, it provides a port on which
+     the memory manager may issue cache management requests, and a port
+     which the kernel will use to name this data region.  In the event
+     that different each will perform a `memory_object_init' call with
+     new request and name ports.  The virtual page size that is used by
+     the calling kernel is included for planning purposes.
+
+     When the memory manager is prepared to accept requests for data
+     for this object, it must call `memory_object_ready' with the
+     attribute.  Otherwise the kernel will not process requests on this
+     object.  To reject all mappings of this object, the memory manager
+     may use `memory_object_destroy'.
+
+     The argument MEMORY_OBJECT is the port that represents the memory
+     object data, as supplied to the kernel in a `vm_map' call.
+     MEMORY_CONTROL is the request port to which a response is
+     requested.  (In the event that a memory object has been supplied
+     to more than one the kernel that has made the request.)
+     MEMORY_OBJECT_NAME is a port used by the kernel to refer to the
+     memory object data in reponse to `vm_region' calls.
+     `memory_object_page_size' is the page size to be used by this
+     kernel.  All data sizes in calls involving this kernel must be an
+     integral multiple of the page size.  Note that different kernels,
+     indicated by a different `memory_control', may have different page
+     sizes.
+
+     The function should return `KERN_SUCCESS', but since this routine
+     is called by the kernel, which does not wait for a reply message,
+     this value is ignored.
+
+ -- Function: kern_return_t memory_object_ready
+          (memory_object_control_t MEMORY_CONTROL,
+          boolean_t MAY_CACHE_OBJECT,
+          memory_object_copy_strategy_t COPY_STRATEGY)
+     The function `memory_object_ready' informs the kernel that the
+     memory manager is ready to receive data or unlock requests on
+     behalf of the clients.  The argument MEMORY_CONTROL is the port,
+     provided by the kernel in a `memory_object_init' call, to which
+     cache management requests may be issued.  If MAY_CACHE_OBJECT is
+     set, the kernel may keep data associated with this memory object,
+     even after virtual memory references to it are gone.
+
+     COPY_STRATEGY tells how the kernel should copy regions of the
+     associated memory object.  There are three possible caching
+     strategies: `MEMORY_OBJECT_COPY_NONE' which specifies that nothing
+     special should be done when data in the object is copied;
+     `MEMORY_OBJECT_COPY_CALL' which specifies that the memory manager
+     should be notified via a `memory_object_copy' call before any part
+     of the object is copied; and `MEMORY_OBJECT_COPY_DELAY' which
+     guarantees that the memory manager does not externally modify the
+     data so that the kernel can use its normal copy-on-write
+     algorithms.  `MEMORY_OBJECT_COPY_DELAY' is the strategy most
+     commonly used.
+
+     This routine does not receive a reply message (and consequently
+     has no return value), so only message transmission errors apply.
+
+
+File: mach.info,  Node: Memory Object Termination,  Next: Memory Objects and Data,  Prev: Memory Object Creation,  Up: External Memory Management
+
+6.3 Memory Object Termination
+=============================
+
+ -- Function: kern_return_t memory_object_terminate
+          (memory_object_t MEMORY_OBJECT,
+          memory_object_control_t MEMORY_CONTROL,
+          memory_object_name_t MEMORY_OBJECT_NAME)
+ -- Function: kern_return_t seqnos_memory_object_terminate
+          (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO,
+          memory_object_control_t MEMORY_CONTROL,
+          memory_object_name_t MEMORY_OBJECT_NAME)
+     The function `memory_object_terminate' indicates that the kernel
+     has completed its use of the given memory object.  All rights to
+     the memory object control and name ports are included, so that the
+     memory manager can destroy them (using `mach_port_deallocate')
+     after doing appropriate bookkeeping.  The kernel will terminate a
+     memory object only after all address space mappings of that memory
+     object have been deallocated, or upon explicit request by the
+     memory manager.
+
+     The argument MEMORY_OBJECT is the port that represents the memory
+     object data, as supplied to the kernel in a `vm_map' call.
+     MEMORY_CONTROL is the request port to which a response is
+     requested.  (In the event that a memory object has been supplied
+     to more than one the kernel that has made the request.)
+     MEMORY_OBJECT_NAME is a port used by the kernel to refer to the
+     memory object data in reponse to `vm_region' calls.
+
+     The function should return `KERN_SUCCESS', but since this routine
+     is called by the kernel, which does not wait for a reply message,
+     this value is ignored.
+
+ -- Function: kern_return_t memory_object_destroy
+          (memory_object_control_t MEMORY_CONTROL, kern_return_t REASON)
+     The function `memory_object_destroy' tells the kernel to shut down
+     the memory object.  As a result of this call the kernel will no
+     longer support paging activity or any `memory_object' calls on this
+     object, and all rights to the memory object port, the memory
+     control port and the memory name port will be returned to the
+     memory manager in a memory_object_terminate call.  If the memory
+     manager is concerned that any modified cached data be returned to
+     it before the object is terminated, it should call
+     `memory_object_lock_request' with SHOULD_FLUSH set and a lock
+     value of `VM_PROT_WRITE' before making this call.
+
+     The argument MEMORY_CONTROL is the port, provided by the kernel in
+     a `memory_object_init' call, to which cache management requests may
+     be issued.  REASON is an error code indicating why the object must
+     be destroyed.
+
+     This routine does not receive a reply message (and consequently
+     has no return value), so only message transmission errors apply.
+
+
+File: mach.info,  Node: Memory Objects and Data,  Next: Memory Object Locking,  Prev: Memory Object Termination,  Up: External Memory Management
+
+6.4 Memory Objects and Data
+===========================
+
+ -- Function: kern_return_t memory_object_data_return
+          (memory_object_t MEMORY_OBJECT,
+          memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET,
+          vm_offset_t DATA, vm_size_t DATA_COUNT, boolean_t DIRTY,
+          boolean_t KERNEL_COPY)
+ -- Function: kern_return_t seqnos_memory_object_data_return
+          (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO,
+          memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET,
+          vm_offset_t DATA, vm_size_t DATA_COUNT, boolean_t DIRTY,
+          boolean_t KERNEL_COPY)
+     The function `memory_object_data_return' provides the memory
+     manager with data that has been modified while cached in physical
+     memory.  Once the memory manager no longer needs this data (e.g.,
+     it has been written to another storage medium), it should be
+     deallocated using `vm_deallocate'.
+
+     The argument MEMORY_OBJECT is the port that represents the memory
+     object data, as supplied to the kernel in a `vm_map' call.
+     MEMORY_CONTROL is the request port to which a response is
+     requested.  (In the event that a memory object has been supplied
+     to more than one the kernel that has made the request.)  OFFSET is
+     the offset within a memory object to which this call refers.  This
+     will be page aligned.  DATA is the data which has been modified
+     while cached in physical memory.  DATA_COUNT is the amount of data
+     to be written, in bytes.  This will be an integral number of
+     memory object pages.
+
+     The kernel will also use this call to return precious pages.  If an
+     unmodified precious age is returned, DIRTY is set to `FALSE',
+     otherwise it is `TRUE'.  If KERNEL_COPY is `TRUE', the kernel kept
+     a copy of the page.  Precious data remains precious if the kernel
+     keeps a copy.  The indication that the kernel kept a copy is only
+     a hint if the data is not precious; the cleaned copy may be
+     discarded without further notifying the manager.
+
+     The function should return `KERN_SUCCESS', but since this routine
+     is called by the kernel, which does not wait for a reply message,
+     this value is ignored.
+
+ -- Function: kern_return_t memory_object_data_request
+          (memory_object_t MEMORY_OBJECT,
+          memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET,
+          vm_offset_t LENGTH, vm_prot_t DESIRED_ACCESS)
+ -- Function: kern_return_t seqnos_memory_object_data_request
+          (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO,
+          memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET,
+          vm_offset_t LENGTH, vm_prot_t DESIRED_ACCESS)
+     The function `memory_object_data_request' is a request for data
+     from the specified memory object, for at least the access
+     specified.  The memory manager is expected to return at least the
+     specified data, with as much access as it can allow, using
+     `memory_object_data_supply'.  If the memory manager is unable to
+     provide the data (for example, because of a hardware error), it
+     may use the `memory_object_data_error' call.  The
+     `memory_object_data_unavailable' call may be used to tell the
+     kernel to supply zero-filled memory for this region.
+
+     The argument MEMORY_OBJECT is the port that represents the memory
+     object data, as supplied to the kernel in a `vm_map' call.
+     MEMORY_CONTROL is the request port to which a response is
+     requested.  (In the event that a memory object has been supplied
+     to more than one the kernel that has made the request.)  OFFSET is
+     the offset within a memory object to which this call refers.  This
+     will be page aligned.  LENGTH is the number of bytes of data,
+     starting at OFFSET, to which this call refers.  This will be an
+     integral number of memory object pages.  DESIRED_ACCESS is a
+     protection value describing the memory access modes which must be
+     permitted on the specified cached data.  One or more of:
+     `VM_PROT_READ', `VM_PROT_WRITE' or `VM_PROT_EXECUTE'.
+
+     The function should return `KERN_SUCCESS', but since this routine
+     is called by the kernel, which does not wait for a reply message,
+     this value is ignored.
+
+ -- Function: kern_return_t memory_object_data_supply
+          (memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET,
+          vm_offset_t DATA, vm_size_t DATA_COUNT, vm_prot_t LOCK_VALUE,
+          boolean_t PRECIOUS, mach_port_t REPLY)
+     The function `memory_object_data_supply' supplies the kernel with
+     data for the specified memory object.  Ordinarily, memory managers
+     should only provide data in reponse to `memory_object_data_request'
+     calls from the kernel (but they may provide data in advance as
+     desired).  When data already held by this kernel is provided
+     again, the new data is ignored.  The kernel may not provide any
+     data (or protection) consistency among pages with different
+     virtual page alignments within the same object.
+
+     The argument MEMORY_CONTROL is the port, provided by the kernel in
+     a `memory_object_init' call, to which cache management requests may
+     be issued.  OFFSET is an offset within a memory object in bytes.
+     This must be page aligned.  DATA is the data that is being
+     provided to the kernel.  This is a pointer to the data.
+     DATA_COUNT is the amount of data to be provided.  Only whole
+     virtual pages of data can be accepted; partial pages will be
+     discarded.
+
+     LOCK_VALUE is a protection value indicating those forms of access
+     that should *not* be permitted to the specified cached data.  The
+     lock values must be one or more of the set: `VM_PROT_NONE',
+     `VM_PROT_READ', `VM_PROT_WRITE', `VM_PROT_EXECUTE' and
+     `VM_PROT_ALL' as defined in `mach/vm_prot.h'.
+
+     If PRECIOUS is `FALSE', the kernel treats the data as a temporary
+     and may throw it away if it hasn't been changed.  If the PRECIOUS
+     value is `TRUE', the kernel treats its copy as a data repository
+     and promises to return it to the manager; the manager may tell the
+     kernel to throw it away instead by flushing and not cleaning the
+     data (see `memory_object_lock_request').
+
+     If REPLY_TO is not `MACH_PORT_NULL', the kernel will send a
+     completion message to the provided port (see
+     `memory_object_supply_completed').
+
+     This routine does not receive a reply message (and consequently
+     has no return value), so only message transmission errors apply.
+
+ -- Function: kern_return_t memory_object_supply_completed
+          (memory_object_t MEMORY_OBJECT,
+          memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET,
+          vm_size_t LENGTH, kern_return_t RESULT,
+          vm_offset_t ERROR_OFFSET)
+ -- Function: kern_return_t seqnos_memory_object_supply_completed
+          (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO,
+          memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET,
+          vm_size_t LENGTH, kern_return_t RESULT,
+          vm_offset_t ERROR_OFFSET)
+     The function `memory_object_supply_completed' indicates that a
+     previous `memory_object_data_supply' has been completed.  Note that
+     this call is made on whatever port was specified in the
+     `memory_object_data_supply' call; that port need not be the memory
+     object port itself.  No reply is expected after this call.
+
+     The argument MEMORY_OBJECT is the port that represents the memory
+     object data, as supplied to the kernel in a `vm_map' call.
+     MEMORY_CONTROL is the request port to which a response is
+     requested.  (In the event that a memory object has been supplied
+     to more than one the kernel that has made the request.)  OFFSET is
+     the offset within a memory object to which this call refers.
+     LENGTH is the length of the data covered by the lock request.  The
+     RESULT parameter indicates what happened during the supply.  If it
+     is not `KERN_SUCCESS', then ERROR_OFFSET identifies the first
+     offset at which a problem occurred.  The pagein operation stopped
+     at this point.  Note that the only failures reported by this
+     mechanism are `KERN_MEMORY_PRESENT'.  All other failures (invalid
+     argument, error on pagein of supplied data in manager's address
+     space) cause the entire operation to fail.
+
+
+ -- Function: kern_return_t memory_object_data_error
+          (memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET,
+          vm_size_t SIZE, kern_return_t REASON)
+     The function `memory_object_data_error' indicates that the memory
+     manager cannot return the data requested for the given region,
+     specifying a reason for the error.  This is typically used when a
+     hardware error is encountered.
+
+     The argument MEMORY_CONTROL is the port, provided by the kernel in
+     a `memory_object_init' call, to which cache management requests may
+     be issued.  OFFSET is an offset within a memory object in bytes.
+     This must be page aligned.  DATA is the data that is being
+     provided to the kernel.  This is a pointer to the data.  SIZE is
+     the amount of cached data (starting at OFFSET) to be handled.
+     This must be an integral number of the memory object page size.
+     REASON is an error code indicating what type of error occured.
+
+     This routine does not receive a reply message (and consequently
+     has no return value), so only message transmission errors apply.
+
+ -- Function: kern_return_t memory_object_data_unavailable
+          (memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET,
+          vm_size_t SIZE, kern_return_t REASON)
+     The function `memory_object_data_unavailable' indicates that the
+     memory object does not have data for the given region and that the
+     kernel should provide the data for this range.  The memory manager
+     may use this call in three different situations.
+
+       1. The object was created by `memory_object_create' and the
+          kernel has not yet provided data for this range (either via a
+          `memory_object_data_initialize', `memory_object_data_write' or
+          a `memory_object_data_return' for the object.
+
+       2. The object was created by an `memory_object_data_copy' and the
+          kernel should copy this region from the original memory
+          object.
+
+       3. The object is a normal user-created memory object and the
+          kernel should supply unlocked zero-filled pages for the range.
+
+     The argument MEMORY_CONTROL is the port, provided by the kernel in
+     a `memory_object_init' call, to which cache management requests may
+     be issued.  OFFSET is an offset within a memory object, in bytes.
+     This must be page aligned.  SIZE is the amount of cached data
+     (starting at OFFSET) to be handled.  This must be an integral
+     number of the memory object page size.
+
+     This routine does not receive a reply message (and consequently
+     has no return value), so only message transmission errors apply.
+
+ -- Function: kern_return_t memory_object_copy
+          (memory_object_t OLD_MEMORY_OBJECT,
+          memory_object_control_t OLD_MEMORY_CONTROL,
+          vm_offset_t OFFSET, vm_size_t LENGTH,
+          memory_object_t NEW_MEMORY_OBJECT)
+ -- Function: kern_return_t seqnos_memory_object_copy
+          (memory_object_t OLD_MEMORY_OBJECT, mach_port_seqno_t SEQNO,
+          memory_object_control_t OLD_MEMORY_CONTROL,
+          vm_offset_t OFFSET, vm_size_t LENGTH,
+          memory_object_t NEW_MEMORY_OBJECT)
+     The function `memory_object_copy' indicates that a copy has been
+     made of the specified range of the given original memory object.
+     This call includes only the new memory object itself; a
+     `memory_object_init' call will be made on the new memory object
+     after the currently cached pages of the original object are
+     prepared.  After the memory manager receives the init call, it
+     must reply with the `memory_object_ready' call to assert the
+     "ready" attribute.  The kernel will use the new memory object,
+     control and name ports to refer to the new copy.
+
+     This call is made when the original memory object had the caching
+     parameter set to `MEMORY_OBJECT_COPY_CALL' and a user of the object
+     has asked the kernel to copy it.
+
+     Cached pages from the original memory object at the time of the
+     copy operation are handled as follows: Readable pages may be
+     silently copied to the new memory object (with all access
+     permissions).  Pages not copied are locked to prevent write access.
+
+     The new memory object is *temporary*, meaning that the memory
+     manager should not change its contents or allow the memory object
+     to be mapped in another client.  The memory manager may use the
+     `memory_object_data_unavailable' call to indicate that the
+     appropriate pages of the original memory object may be used to
+     fulfill the data request.
+
+     The argument OLD_MEMORY_OBJECT is the port that represents the old
+     memory object data.  OLD_MEMORY_CONTROL is the kernel port for the
+     old object.  OFFSET is the offset within a memory object to which
+     this call refers.  This will be page aligned.  LENGTH is the
+     number of bytes of data, starting at OFFSET, to which this call
+     refers.  This will be an integral number of memory object pages.
+     NEW_MEMORY_OBJECT is a new memory object created by the kernel;
+     see synopsis for further description.  Note that all port rights
+     (including receive rights) are included for the new memory object.
+
+     The function should return `KERN_SUCCESS', but since this routine
+     is called by the kernel, which does not wait for a reply message,
+     this value is ignored.
+
+   The remaining interfaces in this section are obsolet.
+
+ -- Function: kern_return_t memory_object_data_write
+          (memory_object_t MEMORY_OBJECT,
+          memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET,
+          vm_offset_t DATA, vm_size_t DATA_COUNT)
+ -- Function: kern_return_t seqnos_memory_object_data_write
+          (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO,
+          memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET,
+          vm_offset_t DATA, vm_size_t DATA_COUNT)
+     The function `memory_object_data_write' provides the memory manager
+     with data that has been modified while cached in physical memory.
+     It is the old form of `memory_object_data_return'.  Once the
+     memory manager no longer needs this data (e.g., it has been written
+     to another storage medium), it should be deallocated using
+     `vm_deallocate'.
+
+     The argument MEMORY_OBJECT is the port that represents the memory
+     object data, as supplied to the kernel in a `vm_map' call.
+     MEMORY_CONTROL is the request port to which a response is
+     requested.  (In the event that a memory object has been supplied
+     to more than one the kernel that has made the request.)  OFFSET is
+     the offset within a memory object to which this call refers.  This
+     will be page aligned.  DATA is the data which has been modified
+     while cached in physical memory.  DATA_COUNT is the amount of data
+     to be written, in bytes.  This will be an integral number of
+     memory object pages.
+
+     The function should return `KERN_SUCCESS', but since this routine
+     is called by the kernel, which does not wait for a reply message,
+     this value is ignored.
+
+ -- Function: kern_return_t memory_object_data_provided
+          (memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET,
+          vm_offset_t DATA, vm_size_t DATA_COUNT, vm_prot_t LOCK_VALUE)
+     The function `memory_object_data_provided' supplies the kernel with
+     data for the specified memory object.  It is the old form of
+     `memory_object_data_supply'.  Ordinarily, memory managers should
+     only provide data in reponse to `memory_object_data_request' calls
+     from the kernel.  The LOCK_VALUE specifies what type of access
+     will not be allowed to the data range.  The lock values must be
+     one or more of the set: `VM_PROT_NONE', `VM_PROT_READ',
+     `VM_PROT_WRITE', `VM_PROT_EXECUTE' and `VM_PROT_ALL' as defined in
+     `mach/vm_prot.h'.
+
+     The argument MEMORY_CONTROL is the port, provided by the kernel in
+     a `memory_object_init' call, to which cache management requests may
+     be issued.  OFFSET is an offset within a memory object in bytes.
+     This must be page aligned.  DATA is the data that is being
+     provided to the kernel.  This is a pointer to the data.
+     DATA_COUNT is the amount of data to be provided.  This must be an
+     integral number of memory object pages.  LOCK_VALUE is a
+     protection value indicating those forms of access that should
+     *not* be permitted to the specified cached data.
+
+     This routine does not receive a reply message (and consequently
+     has no return value), so only message transmission errors apply.
+
+
+File: mach.info,  Node: Memory Object Locking,  Next: Memory Object Attributes,  Prev: Memory Objects and Data,  Up: External Memory Management
+
+6.5 Memory Object Locking
+=========================
+
+ -- Function: kern_return_t memory_object_lock_request
+          (memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET,
+          vm_size_t SIZE, memory_object_return_t SHOULD_CLEAN,
+          boolean_t SHOULD_FLUSH, vm_prot_t LOCK_VALUE,
+          mach_port_t REPLY_TO)
+     The function `memory_object_lock_request' allows a memory manager
+     to make cache management requests.  As specified in arguments to
+     the call, the kernel will:
+        * clean (i.e., write back using `memory_object_data_supply' or
+          `memory_object_data_write') any cached data which has been
+          modified since the last time it was written
+
+        * flush (i.e., remove any uses of) that data from memory
+
+        * lock (i.e., prohibit the specified uses of) the cached data
+
+     Locks applied to cached data are not cumulative; new lock values
+     override previous ones.  Thus, data may also be unlocked using this
+     primitive.  The lock values must be one or more of the following
+     values: `VM_PROT_NONE', `VM_PROT_READ', `VM_PROT_WRITE',
+     `VM_PROT_EXECUTE' and `VM_PROT_ALL' as defined in `mach/vm_prot.h'.
+
+     Only data which is cached at the time of this call is affected.
+     When a running thread requires a prohibited access to cached data,
+     the kernel will issue a `memory_object_data_unlock' call
+     specifying the forms of access required.
+
+     Once all of the actions requested by this call have been
+     completed, the kernel issues a `memory_object_lock_completed' call
+     on the specified reply port.
+
+     The argument MEMORY_CONTROL is the port, provided by the kernel in
+     a `memory_object_init' call, to which cache management requests may
+     be issued.  OFFSET is an offset within a memory object, in bytes.
+     This must be page aligned.  SIZE is the amount of cached data
+     (starting at OFFSET) to be handled.  This must be an integral
+     number of the memory object page size.  If SHOULD_CLEAN is set,
+     modified data should be written back to the memory manager.  If
+     SHOULD_FLUSH is set, the specified cached data should be
+     invalidated, and all uses of that data should be revoked.
+     LOCK_VALUE is a protection value indicating those forms of access
+     that should *not* be permitted to the specified cached data.
+     REPLY_TO is a port on which a `memory_object_lock_comleted' call
+     should be issued, or `MACH_PORT_NULL' if no acknowledgement is
+     desired.
+
+     This routine does not receive a reply message (and consequently
+     has no return value), so only message transmission errors apply.
+
+ -- Function: kern_return_t memory_object_lock_completed
+          (memory_object_t MEMORY_OBJECT,
+          memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET,
+          vm_size_t LENGTH)
+ -- Function: kern_return_t seqnos_memory_object_lock_completed
+          (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO,
+          memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET,
+          vm_size_t LENGTH)
+     The function `memory_object_lock_completed' indicates that a
+     previous `memory_object_lock_request' has been completed.  Note
+     that this call is made on whatever port was specified in the
+     `memory_object_lock_request' call; that port need not be the memory
+     object port itself.  No reply is expected after this call.
+
+     The argument MEMORY_OBJECT is the port that represents the memory
+     object data, as supplied to the kernel in a `vm_map' call.
+     MEMORY_CONTROL is the request port to which a response is
+     requested.  (In the event that a memory object has been supplied
+     to more than one the kernel that has made the request.)  OFFSET is
+     the offset within a memory object to which this call refers.
+     LENGTH is the length of the data covered by the lock request.
+
+     The function should return `KERN_SUCCESS', but since this routine
+     is called by the kernel, which does not wait for a reply message,
+     this value is ignored.
+
+ -- Function: kern_return_t memory_object_data_unlock
+          (memory_object_t MEMORY_OBJECT,
+          memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET,
+          vm_size_t LENGTH, vm_prot_t DESIRED_ACCESS)
+ -- Function: kern_return_t seqnos_memory_object_data_unlock
+          (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO,
+          memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET,
+          vm_size_t LENGTH, vm_prot_t DESIRED_ACCESS)
+     The function `memory_object_data_unlock' is a request that the
+     memory manager permit at least the desired access to the specified
+     data cached by the kernel.  A call to `memory_object_lock_request'
+     is expected in response.
+
+     The argument MEMORY_OBJECT is the port that represents the memory
+     object data, as supplied to the kernel in a `vm_map' call.
+     MEMORY_CONTROL is the request port to which a response is
+     requested.  (In the event that a memory object has been supplied
+     to more than one the kernel that has made the request.)  OFFSET is
+     the offset within a memory object to which this call refers.  This
+     will be page aligned.  LENGTH is the number of bytes of data,
+     starting at OFFSET, to which this call refers.  This will be an
+     integral number of memory object pages.  DESIRED_ACCESS a
+     protection value describing the memory access modes which must be
+     permitted on the specified cached data.  One or more of:
+     `VM_PROT_READ', `VM_PROT_WRITE' or `VM_PROT_EXECUTE'.
+
+     The function should return `KERN_SUCCESS', but since this routine
+     is called by the kernel, which does not wait for a reply message,
+     this value is ignored.
+
+
+File: mach.info,  Node: Memory Object Attributes,  Next: Default Memory Manager,  Prev: Memory Object Locking,  Up: External Memory Management
+
+6.6 Memory Object Attributes
+============================
+
+ -- Function: kern_return_t memory_object_get_attributes
+          (memory_object_control_t MEMORY_CONTROL,
+          boolean_t *OBJECT_READY, boolean_t *MAY_CACHE_OBJECT,
+          memory_object_copy_strategy_t *COPY_STRATEGY)
+     The function `memory_object_get_attribute' retrieves the current
+     attributes associated with the memory object.
+
+     The argument MEMORY_CONTROL is the port, provided by the kernel in
+     a `memory_object_init' call, to which cache management requests may
+     be issued.  If OBJECT_READY is set, the kernel may issue new data
+     and unlock requests on the associated memory object.  If
+     MAY_CACHE_OBJECT is set, the kernel may keep data associated with
+     this memory object, even after virtual memory references to it are
+     gone.  COPY_STRATEGY tells how the kernel should copy regions of
+     the associated memory object.
+
+     This routine does not receive a reply message (and consequently
+     has no return value), so only message transmission errors apply.
+
+ -- Function: kern_return_t memory_object_change_attributes
+          (memory_object_control_t MEMORY_CONTROL,
+          boolean_t MAY_CACHE_OBJECT,
+          memory_object_copy_strategy_t COPY_STRATEGY,
+          mach_port_t REPLY_TO)
+     The function `memory_object_change_attribute' sets
+     performance-related attributes for the specified memory object.
+     If the caching attribute is asserted, the kernel is permitted (and
+     encouraged) to maintain cached data for this memory object even
+     after no virtual address space contains this data.
+
+     There are three possible caching strategies:
+     `MEMORY_OBJECT_COPY_NONE' which specifies that nothing special
+     should be done when data in the object is copied;
+     `MEMORY_OBJECT_COPY_CALL' which specifies that the memory manager
+     should be notified via a `memory_object_copy' call before any part
+     of the object is copied; and `MEMORY_OBJECT_COPY_DELAY' which
+     guarantees that the memory manager does not externally modify the
+     data so that the kernel can use its normal copy-on-write
+     algorithms.  `MEMORY_OBJECT_COPY_DELAY' is the strategy most
+     commonly used.
+
+     The argument MEMORY_CONTROL is the port, provided by the kernel in
+     a `memory_object_init' call, to which cache management requests may
+     be issued.  If MAY_CACHE_OBJECT is set, the kernel may keep data
+     associated with this memory object, even after virtual memory
+     references to it are gone.  COPY_STRATEGY tells how the kernel
+     should copy regions of the associated memory object.  REPLY_TO is
+     a port on which a `memory_object_change_comleted' call will be
+     issued upon completion of the attribute change, or
+     `MACH_PORT_NULL' if no acknowledgement is desired.
+
+     This routine does not receive a reply message (and consequently
+     has no return value), so only message transmission errors apply.
+
+ -- Function: kern_return_t memory_object_change_completed
+          (memory_object_t MEMORY_OBJECT, boolean_t MAY_CACHE_OBJECT,
+          memory_object_copy_strategy_t COPY_STRATEGY)
+ -- Function: kern_return_t seqnos_memory_object_change_completed
+          (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO,
+          boolean_t MAY_CACHE_OBJECT,
+          memory_object_copy_strategy_t COPY_STRATEGY)
+     The function `memory_object_change_completed' indicates the
+     completion of an attribute change call.
+
+
+   The following interface is obsoleted by `memory_object_ready' and
+`memory_object_change_attributes'.  If the old form
+`memory_object_set_attributes' is used to make a memory object ready,
+the kernel will write back data using the old
+`memory_object_data_write' interface rather than
+`memory_object_data_return'..
+
+ -- Function: kern_return_t memory_object_set_attributes
+          (memory_object_control_t MEMORY_CONTROL,
+          boolean OBJECT_READY, boolean_t MAY_CACHE_OBJECT,
+          memory_object_copy_strategy_t COPY_STRATEGY)
+     The function `memory_object_set_attribute' controls how the the
+     memory object.  The kernel will only make data or unlock requests
+     when the ready attribute is asserted.  If the caching attribute is
+     asserted, the kernel is permitted (and encouraged) to maintain
+     cached data for this memory object even after no virtual address
+     space contains this data.
+
+     There are three possible caching strategies:
+     `MEMORY_OBJECT_COPY_NONE' which specifies that nothing special
+     should be done when data in the object is copied;
+     `MEMORY_OBJECT_COPY_CALL' which specifies that the memory manager
+     should be notified via a `memory_object_copy' call before any part
+     of the object is copied; and `MEMORY_OBJECT_COPY_DELAY' which
+     guarantees that the memory manager does not externally modify the
+     data so that the kernel can use its normal copy-on-write
+     algorithms.  `MEMORY_OBJECT_COPY_DELAY' is the strategy most
+     commonly used.
+
+     The argument MEMORY_CONTROL is the port, provided by the kernel in
+     a `memory_object_init' call, to which cache management requests may
+     be issued.  If OBJECT_READY is set, the kernel may issue new data
+     and unlock requests on the associated memory object.  If
+     MAY_CACHE_OBJECT is set, the kernel may keep data associated with
+     this memory object, even after virtual memory references to it are
+     gone.  COPY_STRATEGY tells how the kernel should copy regions of
+     the associated memory object.
+
+     This routine does not receive a reply message (and consequently
+     has no return value), so only message transmission errors apply.
+
+
+File: mach.info,  Node: Default Memory Manager,  Prev: Memory Object Attributes,  Up: External Memory Management
+
+6.7 Default Memory Manager
+==========================
+
+ -- Function: kern_return_t vm_set_default_memory_manager (host_t HOST,
+          mach_port_t *DEFAULT_MANAGER)
+     The function `vm_set_default_memory_manager' sets the kernel's
+     default memory manager.  It sets the port to which newly-created
+     temporary memory objects are delivered by `memory_object_create' to
+     the host.  The old memory manager port is returned.  If
+     DEFAULT_MANAGER is `MACH_PORT_NULL' then this routine just returns
+     the current default manager port without changing it.
+
+     The argument HOST is a task port to the kernel whose default
+     memory manager is to be changed.  DEFAULT_MANAGER is an in/out
+     parameter. As input, DEFAULT_MANAGER is the port that the new
+     memory manager is listening on for `memory_object_create' calls.
+     As output, it is the old default memory manager's port.
+
+     The function returns `KERN_SUCCESS' if the new memory manager is
+     installed, and `KERN_INVALID_ARGUMENT' if this task does not have
+     the privileges required for this call.
+
+ -- Function: kern_return_t memory_object_create
+          (memory_object_t OLD_MEMORY_OBJECT,
+          memory_object_t NEW_MEMORY_OBJECT, vm_size_t NEW_OBJECT_SIZE,
+          memory_object_control_t NEW_CONTROL,
+          memory_object_name_t NEW_NAME, vm_size_t NEW_PAGE_SIZE)
+ -- Function: kern_return_t seqnos_memory_object_create
+          (memory_object_t OLD_MEMORY_OBJECT, mach_port_seqno_t SEQNO,
+          memory_object_t NEW_MEMORY_OBJECT, vm_size_t NEW_OBJECT_SIZE,
+          memory_object_control_t NEW_CONTROL,
+          memory_object_name_t NEW_NAME, vm_size_t NEW_PAGE_SIZE)
+     The function `memory_object_create' is a request that the given
+     memory manager accept responsibility for the given memory object
+     created by the kernel.  This call will only be made to the system
+     *default memory manager*.  The memory object in question initially
+     consists of zero-filled memory; only memory pages that are
+     actually written will ever be provided to
+     `memory_object_data_request' calls, the default memory manager must
+     use `memory_object_data_unavailable' for any pages that have not
+     previously been written.
+
+     No reply is expected after this call.  Since this call is directed
+     to the default memory manager, the kernel assumes that it will be
+     ready to handle data requests to this object and does not need the
+     confirmation of a `memory_object_set_attributes' call.
+
+     The argument OLD_MEMORY_OBJECT is a memory object provided by the
+     default memory manager on which the kernel can make
+     `memory_object_create' calls.  NEW_MEMORY_OBJECT is a new memory
+     object created by the kernel; see synopsis for further
+     description.  Note that all port rights (including receive rights)
+     are included for the new memory object.  NEW_OBJECT_SIZE is the
+     maximum size of the new object.  NEW_CONTROL is a port, created by
+     the kernel, on which a memory manager may issue cache management
+     requests for the new object.  NEW_NAME a port used by the kernel
+     to refer to the new memory object data in response to `vm_region'
+     calls.  NEW_PAGE_SIZE is the page size to be used by this kernel.
+     All data sizes in calls involving this kernel must be an integral
+     multiple of the page size.  Note that different kernels, indicated
+     by different a `memory_control', may have different page sizes.
+
+     The function should return `KERN_SUCCESS', but since this routine
+     is called by the kernel, which does not wait for a reply message,
+     this value is ignored.
+
+ -- Function: kern_return_t memory_object_data_initialize
+          (memory_object_t MEMORY_OBJECT,
+          memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET,
+          vm_offset_t DATA, vm_size_t DATA_COUNT)
+ -- Function: kern_return_t seqnos_memory_object_data_initialize
+          (memory_object_t MEMORY_OBJECT, mach_port_seqno_t SEQNO,
+          memory_object_control_t MEMORY_CONTROL, vm_offset_t OFFSET,
+          vm_offset_t DATA, vm_size_t DATA_COUNT)
+     The function `memory_object_data_initialize' provides the memory
+     manager with initial data for a kernel-created memory object.  If
+     the memory manager already has been supplied data (by a previous
+     `memory_object_data_initialize', `memory_object_data_write' or
+     `memory_object_data_return'), then this data should be ignored.
+     Otherwise, this call behaves exactly as does
+     `memory_object_data_return' on memory objects created by the kernel
+     via `memory_object_create' and thus will only be made to default
+     memory managers.  This call will not be made on objects created via
+     `memory_object_copy'.
+
+     The argument MEMORY_OBJECT the port that represents the memory
+     object data, as supplied by the kernel in a `memory_object_create'
+     call.  MEMORY_CONTROL is the request port to which a response is
+     requested.  (In the event that a memory object has been supplied
+     to more than one the kernel that has made the request.)  OFFSET is
+     the offset within a memory object to which this call refers.  This
+     will be page aligned.  DATA os the data which has been modified
+     while cached in physical memory.  DATA_COUNT is the amount of data
+     to be written, in bytes.  This will be an integral number of
+     memory object pages.
+
+     The function should return `KERN_SUCCESS', but since this routine
+     is called by the kernel, which does not wait for a reply message,
+     this value is ignored.
+
+
+File: mach.info,  Node: Threads and Tasks,  Next: Host Interface,  Prev: External Memory Management,  Up: Top
+
+7 Threads and Tasks
+*******************
+
+* Menu:
+
+* Thread Interface::              Manipulating threads.
+* Task Interface::                Manipulating tasks.
+* Profiling::                     Profiling threads and tasks.
+
+
+File: mach.info,  Node: Thread Interface,  Next: Task Interface,  Up: Threads and Tasks
+
+7.1 Thread Interface
+====================
+
+ -- Data type: thread_t
+     This is a `mach_port_t' and used to hold the port name of a thread
+     port that represents the thread.  Manipulations of the thread are
+     implemented as remote procedure calls to the thread port.  A
+     thread can get a port to itself with the `mach_thread_self' system
+     call.
+
+* Menu:
+
+* Thread Creation::               Creating new threads.
+* Thread Termination::            Terminating existing threads.
+* Thread Information::            How to get informations on threads.
+* Thread Settings::               How to set threads related informations.
+* Thread Execution::              How to control the thread's machine state.
+* Scheduling::                    Operations on thread scheduling.
+* Thread Special Ports::          How to handle the thread's special ports.
+* Exceptions::                    Managing exceptions.
+
+
+File: mach.info,  Node: Thread Creation,  Next: Thread Termination,  Up: Thread Interface
+
+7.1.1 Thread Creation
+---------------------
+
+ -- Function: kern_return_t thread_create (task_t PARENT_TASK,
+          thread_t *CHILD_THREAD)
+     The function `thread_create' creates a new thread within the task
+     specified by PARENT_TASK.  The new thread has no processor state,
+     and has a suspend count of 1.  To get a new thread to run, first
+     `thread_create' is called to get the new thread's identifier,
+     (CHILD_THREAD).  Then `thread_set_state' is called to set a
+     processor state, and finally `thread_resume' is called to get the
+     thread scheduled to execute.
+
+     When the thread is created send rights to its thread kernel port
+     are given to it and returned to the caller in CHILD_THREAD.  The
+     new thread's exception port is set to `MACH_PORT_NULL'.
+
+     The function returns `KERN_SUCCESS' if a new thread has been
+     created, `KERN_INVALID_ARGUMENT' if PARENT_TASK is not a valid
+     task and `KERN_RESOURCE_SHORTAGE' if some critical kernel resource
+     is not available.
+
+
+File: mach.info,  Node: Thread Termination,  Next: Thread Information,  Prev: Thread Creation,  Up: Thread Interface
+
+7.1.2 Thread Termination
+------------------------
+
+ -- Function: kern_return_t thread_terminate (thread_t TARGET_THREAD)
+     The function `thread_terminate' destroys the thread specified by
+     TARGET_THREAD.
+
+     The function returns `KERN_SUCCESS' if the thread has been killed
+     and `KERN_INVALID_ARGUMENT' if TARGET_THREAD is not a thread.
+
+
+File: mach.info,  Node: Thread Information,  Next: Thread Settings,  Prev: Thread Termination,  Up: Thread Interface
+
+7.1.3 Thread Information
+------------------------
+
+ -- Function: thread_t mach_thread_self ()
+     The `mach_thread_self' system call returns the calling thread's
+     thread port.
+
+     `mach_thread_self' has an effect equivalent to receiving a send
+     right for the thread port.  `mach_thread_self' returns the name of
+     the send right.  In particular, successive calls will increase the
+     calling task's user-reference count for the send right.
+
+     As a special exception, the kernel will overrun the user reference
+     count of the thread name port, so that this function can not fail
+     for that reason.  Because of this, the user should not deallocate
+     the port right if an overrun might have happened.  Otherwise the
+     reference count could drop to zero and the send right be destroyed
+     while the user still expects to be able to use it.  As the kernel
+     does not make use of the number of extant send rights anyway, this
+     is safe to do (the thread port itself is not destroyed, even when
+     there are no send rights anymore).
+
+     The function returns `MACH_PORT_NULL' if a resource shortage
+     prevented the reception of the send right or if the thread port is
+     currently null and `MACH_PORT_DEAD' if the thread port is currently
+     dead.
+
+ -- Function: kern_return_t thread_info (thread_t TARGET_THREAD,
+          int FLAVOR, thread_info_t THREAD_INFO,
+          mach_msg_type_number_t *THREAD_INFOCNT)
+     The function `thread_info' returns the selected information array
+     for a thread, as specified by FLAVOR.
+
+     THREAD_INFO is an array of integers that is supplied by the caller
+     and returned filled with specified information.  THREAD_INFOCNT is
+     supplied as the maximum number of integers in THREAD_INFO.  On
+     return, it contains the actual number of integers in THREAD_INFO.
+     The maximum number of integers returned by any flavor is
+     `THREAD_INFO_MAX'.
+
+     The type of information returned is defined by FLAVOR, which can
+     be one of the following:
+
+    `THREAD_BASIC_INFO'
+          The function returns basic information about the thread, as
+          defined by `thread_basic_info_t'.  This includes the user and
+          system time, the run state, and scheduling priority.  The
+          number of integers returned is `THREAD_BASIC_INFO_COUNT'.
+
+    `THREAD_SCHED_INFO'
+          The function returns information about the schduling policy
+          for the thread as defined by `thread_sched_info_t'.  The
+          number of integers returned is `THREAD_SCHED_INFO_COUNT'.
+
+     The function returns `KERN_SUCCESS' if the call succeeded and
+     `KERN_INVALID_ARGUMENT' if TARGET_THREAD is not a thread or FLAVOR
+     is not recognized.  The function returns `MIG_ARRAY_TOO_LARGE' if
+     the returned info array is too large for THREAD_INFO.  In this
+     case, THREAD_INFO is filled as much as possible and THREAD_INFOCNT
+     is set to the number of elements that would have been returned if
+     there were enough room.
+
+ -- Data type: struct thread_basic_info
+     This structure is returned in THREAD_INFO by the `thread_info'
+     function and provides basic information about the thread.  You can
+     cast a variable of type `thread_info_t' to a pointer of this type
+     if you provided it as the THREAD_INFO parameter for the
+     `THREAD_BASIC_INFO' flavor of `thread_info'.  It has the following
+     members:
+
+    `time_value_t user_time'
+          user run time
+
+    `time_value_t system_time'
+          system run time
+
+    `int cpu_usage'
+          Scaled cpu usage percentage.  The scale factor is
+          `TH_USAGE_SCALE'.
+
+    `int base_priority'
+          The base scheduling priority of the thread.
+
+    `int cur_priority'
+          The current scheduling priority of the thread.
+
+    `integer_t run_state'
+          The run state of the thread.  The possible vlues of this
+          field are:
+         `TH_STATE_RUNNING'
+               The thread is running normally.
+
+         `TH_STATE_STOPPED'
+               The thread is suspended.
+
+         `TH_STATE_WAITING'
+               The thread is waiting normally.
+
+         `TH_STATE_UNINTERRUPTIBLE'
+               The thread is in an uninterruptible wait.
+
+         `TH_STATE_HALTED'
+               The thread is halted at a clean point.
+
+    `flags'
+          Various flags.  The possible values of this field are:
+         `TH_FLAGS_SWAPPED'
+               The thread is swapped out.
+
+         `TH_FLAGS_IDLE'
+               The thread is an idle thread.
+
+    `int suspend_count'
+          The suspend count for the thread.
+
+    `int sleep_time'
+          The number of seconds that the thread has been sleeping.
+
+    `time_value_t creation_time'
+          The time stamp of creation.
+
+ -- Data type: thread_basic_info_t
+     This is a pointer to a `struct thread_basic_info'.
+
+ -- Data type: struct thread_sched_info
+     This structure is returned in THREAD_INFO by the `thread_info'
+     function and provides schedule information about the thread.  You
+     can cast a variable of type `thread_info_t' to a pointer of this
+     type if you provided it as the THREAD_INFO parameter for the
+     `THREAD_SCHED_INFO' flavor of `thread_info'.  It has the following
+     members:
+
+    `int policy'
+          The scheduling policy of the thread, *Note Scheduling
+          Policy::.
+
+    `integer_t data'
+          Policy-dependent scheduling information, *Note Scheduling
+          Policy::.
+
+    `int base_priority'
+          The base scheduling priority of the thread.
+
+    `int max_priority'
+          The maximum scheduling priority of the thread.
+
+    `int cur_priority'
+          The current scheduling priority of the thread.
+
+    `int depressed'
+          `TRUE' if the thread is depressed.
+
+    `int depress_priority'
+          The priority the thread was depressed from.
+
+ -- Data type: thread_sched_info_t
+     This is a pointer to a `struct thread_sched_info'.
+
+
+File: mach.info,  Node: Thread Settings,  Next: Thread Execution,  Prev: Thread Information,  Up: Thread Interface
+
+7.1.4 Thread Settings
+---------------------
+
+ -- Function: kern_return_t thread_wire (host_priv_t HOST_PRIV,
+          thread_t THREAD, boolean_t WIRED)
+     The function `thread_wire' controls the VM privilege level of the
+     thread THREAD.  A VM-privileged thread never waits inside the
+     kernel for memory allocation from the kernel's free list of pages
+     or for allocation of a kernel stack.
+
+     Threads that are part of the default pageout path should be
+     VM-privileged, to prevent system deadlocks.  Threads that are not
+     part of the default pageout path should not be VM-privileged, to
+     prevent the kernel's free list of pages from being exhausted.
+
+     The functions returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_ARGUMENT' if HOST_PRIV or THREAD was invalid.
+
+     The `thread_wire' call is actually an RPC to HOST_PRIV, normally a
+     send right for a privileged host port, but potentially any send
+     right.  In addition to the normal diagnostic return codes from the
+     call's server (normally the kernel), the call may return `mach_msg'
+     return codes.
+
+
+File: mach.info,  Node: Thread Execution,  Next: Scheduling,  Prev: Thread Settings,  Up: Thread Interface
+
+7.1.5 Thread Execution
+----------------------
+
+ -- Function: kern_return_t thread_suspend (thread_t TARGET_THREAD)
+     Increments the thread's suspend count and prevents the thread from
+     executing any more user level instructions.  In this context a user
+     level instruction is either a machine instruction executed in user
+     mode or a system trap instruction including page faults.  Thus if
+     a thread is currently executing within a system trap the kernel
+     code may continue to execute until it reaches the system return
+     code or it may supend within the kernel code.  In either case,
+     when the thread is resumed the system trap will return.  This
+     could cause unpredictible results if the user did a suspend and
+     then altered the user state of the thread in order to change its
+     direction upon a resume.  The call `thread_abort' is provided to
+     allow the user to abort any system call that is in progress in a
+     predictable way.
+
+     The suspend count may become greater than one with the effect that
+     it will take more than one resume call to restart the thread.
+
+     The function returns `KERN_SUCCESS' if the thread has been
+     suspended and `KERN_INVALID_ARGUMENT' if TARGET_THREAD is not a
+     thread.
+
+ -- Function: kern_return_t thread_resume (thread_t TARGET_THREAD)
+     Decrements the threads's suspend count.  If the count becomes zero
+     the thread is resumed.  If it is still positive, the thread is left
+     suspended.  The suspend count may not become negative.
+
+     The function returns `KERN_SUCCESS' if the thread has been resumed,
+     `KERN_FAILURE' if the suspend count is already zero and
+     `KERN_INVALID_ARGUMENT' if TARGET_THREAD is not a thread.
+
+ -- Function: kern_return_t thread_abort (thread_t TARGET_THREAD)
+     The function `thread_abort' aborts the kernel primitives:
+     `mach_msg', `msg_send', `msg_receive' and `msg_rpc' and
+     page-faults, making the call return a code indicating that it was
+     interrupted.  The call is interrupted whether or not the thread
+     (or task containing it) is currently suspended.  If it is
+     supsended, the thread receives the interupt when it is resumed.
+
+     A thread will retry an aborted page-fault if its state is not
+     modified before it is resumed.  `msg_send' returns
+     `SEND_INTERRUPTED'; `msg_receive' returns `RCV_INTERRUPTED';
+     `msg_rpc' returns either `SEND_INTERRUPTED' or `RCV_INTERRUPTED',
+     depending on which half of the RPC was interrupted.
+
+     The main reason for this primitive is to allow one thread to
+     cleanly stop another thread in a manner that will allow the future
+     execution of the target thread to be controlled in a predictable
+     way.  `thread_suspend' keeps the target thread from executing any
+     further instructions at the user level, including the return from
+     a system call.  `thread_get_state'/`thread_set_state' allows the
+     examination or modification of the user state of a target thread.
+     However, if a suspended thread was executing within a system call,
+     it also has associated with it a kernel state.  This kernel state
+     can not be modified by `thread_set_state' with the result that
+     when the thread is resumed the system call may return changing the
+     user state and possibly user memory.  `thread_abort' aborts the
+     kernel call from the target thread's point of view by resetting
+     the kernel state so that the thread will resume execution at the
+     system call return with the return code value set to one of the
+     interrupted codes.  The system call itself will either be entirely
+     completed or entirely aborted, depending on the precise moment at
+     which the abort was received.  Thus if the thread's user state has
+     been changed by `thread_set_state', it will not be modified by any
+     unexpected system call side effects.
+
+     For example to simulate a Unix signal, the following sequence of
+     calls may be used:
+
+       1. `thread_suspend': Stops the thread.
+
+       2. `thread_abort': Interrupts any system call in progress,
+          setting the return value to `interrupted'.  Since the thread
+          is stopped, it will not return to user code.
+
+       3. `thread_set_state': Alters thread's state to simulate a
+          procedure call to the signal handler
+
+       4. `thread_resume': Resumes execution at the signal handler.  If
+          the thread's stack has been correctly set up, the thread may
+          return to the interrupted system call.  (Of course, the code
+          to push an extra stack frame and change the registers is VERY
+          machine-dependent.)
+
+     Calling `thread_abort' on a non-suspended thread is pretty risky,
+     since it is very difficult to know exactly what system trap, if
+     any, the thread might be executing and whether an interrupt return
+     would cause the thread to do something useful.
+
+     The function returns `KERN_SUCCESS' if the thread received an
+     interrupt and `KERN_INVALID_ARGUMENT' if TARGET_THREAD is not a
+     thread.
+
+ -- Function: kern_return_t thread_get_state (thread_t TARGET_THREAD,
+          int FLAVOR, thread_state_t OLD_STATE,
+          mach_msg_type_number_t *OLD_STATECNT)
+     The function `thread_get_state' returns the execution state (e.g.
+     the machine registers) of TARGET_THREAD as specified by FLAVOR.
+     The OLD_STATE is an array of integers that is provided by the
+     caller and returned filled with the specified information.
+     OLD_STATECNT is input set to the maximum number of integers in
+     OLD_STATE and returned equal to the actual number of integers in
+     OLD_STATE.
+
+     TARGET_THREAD may not be `mach_thread_self()'.
+
+     The definition of the state structures can be found in
+     `machine/thread_status.h'.
+
+     The function returns `KERN_SUCCESS' if the state has been returned,
+     `KERN_INVALID_ARGUMENT' if TARGET_THREAD is not a thread or is
+     `mach_thread_self' or FLAVOR is unrecogized for this machine.  The
+     function returns `MIG_ARRAY_TOO_LARGE' if the returned state is
+     too large for OLD_STATE.  In this case, OLD_STATE is filled as
+     much as possible and OLD_STATECNT is set to the number of elements
+     that would have been returned if there were enough room.
+
+ -- Function: kern_return_t thread_set_state (thread_t TARGET_THREAD,
+          int FLAVOR, thread_state_t NEW_STATE,
+          mach_msg_type_number_t NEW_STATE_COUNT)
+     The function `thread_set_state' sets the execution state (e.g. the
+     machine registers) of TARGET_THREAD as specified by FLAVOR.  The
+     NEW_STATE is an array of integers.  NEW_STATE_COUNT is the number
+     of elements in NEW_STATE.  The entire set of registers is reset.
+     This will do unpredictable things if TARGET_THREAD is not
+     suspended.
+
+     TARGET_THREAD may not be `mach_thread_self'.
+
+     The definition of the state structures can be found in
+     `machine/thread_status.h'.
+
+     The function returns `KERN_SUCCESS' if the state has been set and
+     `KERN_INVALID_ARGUMENT' if TARGET_THREAD is not a thread or is
+     `mach_thread_self' or FLAVOR is unrecogized for this machine.
+
+
+File: mach.info,  Node: Scheduling,  Next: Thread Special Ports,  Prev: Thread Execution,  Up: Thread Interface
+
+7.1.6 Scheduling
+----------------
+
+* Menu:
+
+* Thread Priority::               Changing the priority of a thread.
+* Hand-Off Scheduling::           Switching to a new thread.
+* Scheduling Policy::             Setting the scheduling policy.
+
+
+File: mach.info,  Node: Thread Priority,  Next: Hand-Off Scheduling,  Up: Scheduling
+
+7.1.6.1 Thread Priority
+.......................
+
+Threads have three priorities associated with them by the system, a
+priority, a maximum priority, and a scheduled priority.  The scheduled
+priority is used to make scheduling decisions about the thread.  It is
+determined from the priority by the policy (for timesharing, this means
+adding an increment derived from cpu usage).  The priority can be set
+under user control, but may never exceed the maximum priority.  Changing
+the maximum priority requires presentation of the control port for the
+thread's processor set; since the control port for the default processor
+set is privileged, users cannot raise their maximum priority to unfairly
+compete with other users on that set.  Newly created threads obtain
+their priority from their task and their max priority from the thread.
+
+ -- Function: kern_return_t thread_priority (thread_t THREAD,
+          int PRORITY, boolean_t SET_MAX)
+     The function `thread_priority' changes the priority and optionally
+     the maximum priority of THREAD.  Priorities range from 0 to 31,
+     where lower numbers denote higher priorities.  If the new priority
+     is higher than the priority of the current thread, preemption may
+     occur as a result of this call.  The maximum priority of the
+     thread is also set if SET_MAX is `TRUE'.  This call will fail if
+     PRIORITY is greater than the current maximum priority of the
+     thread.  As a result, this call can only lower the value of a
+     thread's maximum priority.
+
+     The functions returns `KERN_SUCCESS' if the operation completed
+     successfully, `KERN_INVALID_ARGUMENT' if THREAD is not a thread or
+     PRIORITY is out of range (not in 0..31), and `KERN_FAILURE' if the
+     requested operation would violate the thread's maximum priority
+     (thread_priority).
+
+ -- Function: kern_return_t thread_max_priority (thread_t THREAD,
+          processor_set_t PROCESSOR_SET, int PRIORITY)
+     The function `thread_max_priority' changes the maximum priority of
+     the thread.  Because it requires presentation of the corresponding
+     processor set port, this call can reset the maximum priority to any
+     legal value.
+
+     The functions returns `KERN_SUCCESS' if the operation completed
+     successfully, `KERN_INVALID_ARGUMENT' if THREAD is not a thread or
+     PROCESSOR_SET is not a control port for a processor set or
+     PRIORITY is out of range (not in 0..31), and `KERN_FAILURE' if the
+     thread is not assigned to the processor set whose control port was
+     presented.
+
+
+File: mach.info,  Node: Hand-Off Scheduling,  Next: Scheduling Policy,  Prev: Thread Priority,  Up: Scheduling
+
+7.1.6.2 Hand-Off Scheduling
+...........................
+
+ -- Function: kern_return_t thread_switch (thread_t NEW_THREAD,
+          int OPTION, int TIME)
+     The function `thread_switch' provides low-level access to the
+     scheduler's context switching code.  NEW_THREAD is a hint that
+     implements hand-off scheduling.  The operating system will attempt
+     to switch directly to the new thread (by passing the normal logic
+     that selects the next thread to run) if possible.  Since this is a
+     hint, it may be incorrect; it is ignored if it doesn't specify a
+     thread on the same host as the current thread or if that thread
+     can't be switched to (i.e., not runnable or already running on
+     another processor).  In this case, the normal logic to select the
+     next thread to run is used; the current thread may continue
+     running if there is no other appropriate thread to run.
+
+     Options for OPTION are defined in `mach/thread_switch.h' and
+     specify the interpretation of TIME.  The possible values for
+     OPTION are:
+
+    `SWITCH_OPTION_NONE'
+          No options, the time argument is ignored.
+
+    `SWITCH_OPTION_WAIT'
+          The thread is blocked for the specified time.  This can be
+          aborted by `thread_abort'.
+
+    `SWITCH_OPTION_DEPRESS'
+          The thread's priority is depressed to the lowest possible
+          value for the specified time.  This can be aborted by
+          `thread_depress_abort'.  This depression is independent of
+          operations that change the thread's priority (e.g.
+          `thread_priority' will not abort the depression).  The
+          minimum time and units of time can be obtained as the
+          `min_timeout' value from `host_info'.  The depression is also
+          aborted when the current thread is next run (either via
+          hand­off scheduling or because the processor set has nothing
+          better to do).
+
+     `thread_switch' is often called when the current thread can proceed
+     no further for some reason; the various options and arguments allow
+     information about this reason to be transmitted to the kernel.  The
+     NEW_THREAD argument (handoff scheduling) is useful when the
+     identity of the thread that must make progress before the current
+     thread runs again is known.  The `WAIT' option is used when the
+     amount of time that the current thread must wait before it can do
+     anything useful can be estimated and is fairly long.  The
+     `DEPRESS' option is used when the amount of time that must be
+     waited is fairly short, especially when the identity of the thread
+     that is being waited for is not known.
+
+     Users should beware of calling `thread_switch' with an invalid hint
+     (e.g. `MACH_PORT_NULL') and no option.  Because the time-sharing
+     scheduler varies the priority of threads based on usage, this may
+     result in a waste of cpu time if the thread that must be run is of
+     lower priority.  The use of the `DEPRESS' option in this situation
+     is highly recommended.
+
+     `thread_switch' ignores policies.  Users relying on the preemption
+     semantics of a fixed time policy should be aware that
+     `thread_switch' ignores these semantics; it will run the specified
+     NEW_THREAD indepent of its priority and the priority of any other
+     threads that could be run instead.
+
+     The function returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_ARGUMENT' if THREAD is not a thread or OPTION is not
+     a recognized option, and `KERN_FAILURE' if `kern_depress_abort'
+     failed because the thread was not depressed.
+
+ -- Function: kern_return_t thread_depress_abort (thread_t THREAD)
+     The function `thread_depress_abort' cancels any priority depression
+     for THREAD caused by a `swtch_pri' or `thread_switch' call.
+
+     The function returns `KERN_SUCCESS' if the call succeeded and
+     `KERN_INVALID_ARGUMENT' if THREAD is not a valid thread.
+
+ -- Function: boolean_t swtch ()
+     The system trap `swtch' attempts to switch the current thread off
+     the processor.  The return value indicates if more than the current
+     thread is running in the processor set.  This is useful for lock
+     management routines.
+
+     The call returns `FALSE' if the thread is justified in becoming a
+     resource hog by continuing to spin because there's nothing else
+     useful that the processor could do.  `TRUE' is returned if the
+     thread should make one more check on the lock and then be a good
+     citizen and really suspend.
+
+ -- Function: boolean_t swtch_pri (int PRIORITY)
+     The system trap `swtch_pri' attempts to switch the current thread
+     off the processor as `swtch' does, but depressing the priority of
+     the thread to the minimum possible value during the time.
+     PRIORITY is not used currently.
+
+     The return value is as for `swtch'.
+
+
+File: mach.info,  Node: Scheduling Policy,  Prev: Hand-Off Scheduling,  Up: Scheduling
+
+7.1.6.3 Scheduling Policy
+.........................
+
+ -- Function: kern_return_t thread_policy (thread_t THREAD, int POLICY,
+          int DATA)
+     The function `thread_policy' changes the scheduling policy for
+     THREAD to POLICY.
+
+     DATA is policy-dependent scheduling information.  There are
+     currently two supported policies: `POLICY_TIMESHARE' and
+     `POLICY_FIXEDPRI' defined in `mach/policy.h'; this file is
+     included by `mach.h'.  DATA is meaningless for timesharing, but is
+     the quantum to be used (in milliseconds) for the fixed priority
+     policy.  To be meaningful, this quantum must be a multiple of the
+     basic system quantum (min_quantum) which can be obtained from
+     `host_info'.  The system will always round up to the next multiple
+     of the quantum.
+
+     Processor sets may restrict the allowed policies, so this call
+     will fail if the processor set to which THREAD is currently
+     assigned does not permit POLICY.
+
+     The function returns `KERN_SUCCESS' if the call succeeded.
+     `KERN_INVALID_ARGUMENT' if THREAD is not a thread or POLICY is not
+     a recognized policy, and `KERN_FAILURE' if the processor set to
+     which THREAD is currently assigned does not permit POLICY.
+
+
+File: mach.info,  Node: Thread Special Ports,  Next: Exceptions,  Prev: Scheduling,  Up: Thread Interface
+
+7.1.7 Thread Special Ports
+--------------------------
+
+ -- Function: kern_return_t thread_get_special_port (thread_t THREAD,
+          int WHICH_PORT, mach_port_t *SPECIAL_PORT)
+     The function `thread_get_special_port' returns send rights to one
+     of a set of special ports for the thread specified by THREAD.
+
+     The possible values for WHICH_PORT are `THREAD_KERNEL_PORT' and
+     `THREAD_EXCEPTION_PORT'.  A thread also has access to its task's
+     special ports.
+
+     The function returns `KERN_SUCCESS' if the port was returned and
+     `KERN_INVALID_ARGUMENT' if THREAD is not a thread or WHICH_PORT is
+     an invalid port selector.
+
+ -- Function: kern_return_t thread_get_kernel_port (thread_t THREAD,
+          mach_port_t *KERNEL_PORT)
+     The function `thread_get_kernel_port' is equivalent to the function
+     `thread_get_special_port' with the WHICH_PORT argument set to
+     `THREAD_KERNEL_PORT'.
+
+ -- Function: kern_return_t thread_get_exception_port (thread_t THREAD,
+          mach_port_t *EXCEPTION_PORT)
+     The function `thread_get_exception_port' is equivalent to the
+     function `thread_get_special_port' with the WHICH_PORT argument
+     set to `THREAD_EXCEPTION_PORT'.
+
+ -- Function: kern_return_t thread_set_special_port (thread_t THREAD,
+          int WHICH_PORT, mach_port_t SPECIAL_PORT)
+     The function `thread_set_special_port' sets one of a set of special
+     ports for the thread specified by THREAD.
+
+     The possible values for WHICH_PORT are `THREAD_KERNEL_PORT' and
+     `THREAD_EXCEPTION_PORT'.  A thread also has access to its task's
+     special ports.
+
+     The function returns `KERN_SUCCESS' if the port was set and
+     `KERN_INVALID_ARGUMENT' if THREAD is not a thread or WHICH_PORT is
+     an invalid port selector.
+
+ -- Function: kern_return_t thread_set_kernel_port (thread_t THREAD,
+          mach_port_t KERNEL_PORT)
+     The function `thread_set_kernel_port' is equivalent to the function
+     `thread_set_special_port' with the WHICH_PORT argument set to
+     `THREAD_KERNEL_PORT'.
+
+ -- Function: kern_return_t thread_set_exception_port (thread_t THREAD,
+          mach_port_t EXCEPTION_PORT)
+     The function `thread_set_exception_port' is equivalent to the
+     function `thread_set_special_port' with the WHICH_PORT argument
+     set to `THREAD_EXCEPTION_PORT'.
+
+
+File: mach.info,  Node: Exceptions,  Prev: Thread Special Ports,  Up: Thread Interface
+
+7.1.8 Exceptions
+----------------
+
+ -- Function: kern_return_t catch_exception_raise
+          (mach_port_t EXCEPTION_PORT, thread_t THREAD, task_t TASK,
+          int EXCEPTION, int CODE, int SUBCODE)
+     XXX Fixme
+
+ -- Function: kern_return_t exception_raise
+          (mach_port_t EXCEPTION_PORT, mach_port_t THREAD,
+          mach_port_t TASK, integer_t EXCEPTION, integer_t CODE,
+          integer_t SUBCODE)
+     XXX Fixme
+
+ -- Function: kern_return_t evc_wait (unsigned int EVENT)
+     The system trap `evc_wait' makes the calling thread wait for the
+     event specified by EVENT.
+
+     The call returns `KERN_SUCCESS' if the event has occured,
+     `KERN_NO_SPACE' if another thread is waiting for the same event and
+     `KERN_INVALID_ARGUMENT' if the event object is invalid.
+
+
+File: mach.info,  Node: Task Interface,  Next: Profiling,  Prev: Thread Interface,  Up: Threads and Tasks
+
+7.2 Task Interface
+==================
+
+ -- Data type: task_t
+     This is a `mach_port_t' and used to hold the port name of a task
+     port that represents the thread.  Manipulations of the task are
+     implemented as remote procedure calls to the task port.  A task
+     can get a port to itself with the `mach_task_self' system call.
+
+     The task port name is also used to identify the task's IPC space
+     (*note Port Manipulation Interface::) and the task's virtual
+     memory map (*note Virtual Memory Interface::).
+
+* Menu:
+
+* Task Creation::                 Creating tasks.
+* Task Termination::              Terminating tasks.
+* Task Information::              Informations on tasks.
+* Task Execution::                Thread scheduling in a task.
+* Task Special Ports::            How to get and set the task's special ports.
+* Syscall Emulation::             How to emulate system calls.
+
+
+File: mach.info,  Node: Task Creation,  Next: Task Termination,  Up: Task Interface
+
+7.2.1 Task Creation
+-------------------
+
+ -- Function: kern_return_t task_create (task_t PARENT_TASK,
+          boolean_t INHERIT_MEMORY, task_t *CHILD_TASK)
+     The function `task_create' creates a new task from PARENT_TASK;
+     the resulting task (CHILD_TASK) acquires shared or copied parts of
+     the parent's address space (see `vm_inherit').  The child task
+     initially contains no threads.
+
+     If INHERIT_MEMORY is set, the child task's address space is built
+     from the parent task according to its memory inheritance values;
+     otherwise, the child task is given an empty address space.
+
+     The child task gets the three special ports created or copied for
+     it at task creation.  The `TASK_KERNEL_PORT' is created and send
+     rights for it are given to the child and returned to the caller.
+     The `TASK_BOOTSTRAP_PORT' and the `TASK_EXCEPTION_PORT' are
+     inherited from the parent task.  The new task can get send rights
+     to these ports with the call `task_get_special_port'.
+
+     The function returns `KERN_SUCCESS' if a new task has been created,
+     `KERN_INVALID_ARGUMENT' if PARENT_TASK is not a valid task port
+     and `KERN_RESOURCE_SHORTAGE' if some critical kernel resource is
+     unavailable.
+
+
+File: mach.info,  Node: Task Termination,  Next: Task Information,  Prev: Task Creation,  Up: Task Interface
+
+7.2.2 Task Termination
+----------------------
+
+ -- Function: kern_return_t task_terminate (task_t TARGET_TASK)
+     The function `task_terminate' destroys the task specified by
+     TARGET_TASK and all its threads.  All resources that are used only
+     by this task are freed.  Any port to which this task has receive
+     and ownership rights is destroyed.
+
+     The function returns `KERN_SUCCESS' if the task has been killed,
+     `KERN_INVALID_ARGUMENT' if TARGET_TASK is not a task.
+
+
+File: mach.info,  Node: Task Information,  Next: Task Execution,  Prev: Task Termination,  Up: Task Interface
+
+7.2.3 Task Information
+----------------------
+
+ -- Function: task_t mach_task_self ()
+     The `mach_task_self' system call returns the calling thread's task
+     port.
+
+     `mach_task_self' has an effect equivalent to receiving a send right
+     for the task port.  `mach_task_self' returns the name of the send
+     right.  In particular, successive calls will increase the calling
+     task's user-reference count for the send right.
+
+     As a special exception, the kernel will overrun the user reference
+     count of the task name port, so that this function can not fail
+     for that reason.  Because of this, the user should not deallocate
+     the port right if an overrun might have happened.  Otherwise the
+     reference count could drop to zero and the send right be destroyed
+     while the user still expects to be able to use it.  As the kernel
+     does not make use of the number of extant send rights anyway, this
+     is safe to do (the task port itself is not destroyed, even when
+     there are no send rights anymore).
+
+     The funcion returns `MACH_PORT_NULL' if a resource shortage
+     prevented the reception of the send right, `MACH_PORT_NULL' if the
+     task port is currently null, `MACH_PORT_DEAD' if the task port is
+     currently dead.
+
+ -- Function: kern_return_t task_threads (task_t TARGET_TASK,
+          thread_array_t *THREAD_LIST,
+          mach_msg_type_number_t *THREAD_COUNT)
+     The function `task_threads' gets send rights to the kernel port for
+     each thread contained in TARGET_TASK.  THREAD_LIST is an array
+     that is created as a result of this call.  The caller may wish to
+     `vm_deallocate' this array when the data is no longer needed.
+
+     The function returns `KERN_SUCCESS' if the call succeeded and
+     `KERN_INVALID_ARGUMENT' if TARGET_TASK is not a task.
+
+ -- Function: kern_return_t task_info (task_t TARGET_TASK, int FLAVOR,
+          task_info_t TASK_INFO,
+          mach_msg_type_number_t *TASK_INFO_COUNT)
+     The function `task_info' returns the selected information array for
+     a task, as specified by FLAVOR.  TASK_INFO is an array of integers
+     that is supplied by the caller, and filled with specified
+     information.  TASK_INFO_COUNT is supplied as the maximum number of
+     integers in TASK_INFO.  On return, it contains the actual number
+     of integers in TASK_INFO.  The maximum number of integers returned
+     by any flavor is `TASK_INFO_MAX'.
+
+     The type of information returned is defined by FLAVOR, which can
+     be one of the following:
+
+    `TASK_BASIC_INFO'
+          The function returns basic information about the task, as
+          defined by `task_basic_info_t'.  This includes the user and
+          system time and memory consumption.  The number of integers
+          returned is `TASK_BASIC_INFO_COUNT'.
+
+    `TASK_EVENTS_INFO'
+          The function returns information about events for the task as
+          defined by `thread_sched_info_t'.  This includes statistics
+          about virtual memory and IPC events like pageouts, pageins
+          and messages sent and received.  The number of integers
+          returned is `TASK_EVENTS_INFO_COUNT'.
+
+    `TASK_THREAD_TIMES_INFO'
+          The function returns information about the total time for
+          live threads as defined by `task_thread_times_info_t'.  The
+          number of integers returned is `TASK_THREAD_TIMES_INFO_COUNT'.
+
+     The function returns `KERN_SUCCESS' if the call succeeded and
+     `KERN_INVALID_ARGUMENT' if TARGET_TASK is not a thread or FLAVOR
+     is not recognized.  The function returns `MIG_ARRAY_TOO_LARGE' if
+     the returned info array is too large for TASK_INFO.  In this case,
+     TASK_INFO is filled as much as possible and TASK_INFOCNT is set to
+     the number of elements that would have been returned if there were
+     enough room.
+
+ -- Data type: struct task_basic_info
+     This structure is returned in TASK_INFO by the `task_info'
+     function and provides basic information about the task.  You can
+     cast a variable of type `task_info_t' to a pointer of this type if
+     you provided it as the TASK_INFO parameter for the
+     `TASK_BASIC_INFO' flavor of `task_info'.  It has the following
+     members:
+
+    `integer_t suspend_count'
+          suspend count for task
+
+    `integer_t base_priority'
+          base scheduling priority
+
+    `vm_size_t virtual_size'
+          number of virtual pages
+
+    `vm_size_t resident_size'
+          number of resident pages
+
+    `time_value_t user_time'
+          total user run time for terminated threads
+
+    `time_value_t system_time'
+          total system run time for terminated threads
+
+    `time_value_t creation_time'
+          creation time stamp
+
+ -- Data type: task_basic_info_t
+     This is a pointer to a `struct task_basic_info'.
+
+ -- Data type: struct task_events_info
+     This structure is returned in TASK_INFO by the `task_info'
+     function and provides event statistics for the task.  You can cast
+     a variable of type `task_info_t' to a pointer of this type if you
+     provided it as the TASK_INFO parameter for the `TASK_EVENTS_INFO'
+     flavor of `task_info'.  It has the following members:
+
+    `natural_t faults'
+          number of page faults
+
+    `natural_t zero_fills'
+          number of zero fill pages
+
+    `natural_t reactivations'
+          number of reactivated pages
+
+    `natural_t pageins'
+          number of actual pageins
+
+    `natural_t cow_faults'
+          number of copy-on-write faults
+
+    `natural_t messages_sent'
+          number of messages sent
+
+    `natural_t messages_received'
+          number of messages received
+
+ -- Data type: task_events_info_t
+     This is a pointer to a `struct task_events_info'.
+
+ -- Data type: struct task_thread_times_info
+     This structure is returned in TASK_INFO by the `task_info'
+     function and provides event statistics for the task.  You can cast
+     a variable of type `task_info_t' to a pointer of this type if you
+     provided it as the TASK_INFO parameter for the
+     `TASK_THREAD_TIMES_INFO' flavor of `task_info'.  It has the
+     following members:
+
+    `time_value_t user_time'
+          total user run time for live threads
+
+    `time_value_t system_time'
+          total system run time for live threads
+
+ -- Data type: task_thread_times_info_t
+     This is a pointer to a `struct task_thread_times_info'.
+
+
+File: mach.info,  Node: Task Execution,  Next: Task Special Ports,  Prev: Task Information,  Up: Task Interface
+
+7.2.4 Task Execution
+--------------------
+
+ -- Function: kern_return_t task_suspend (task_t TARGET_TASK)
+     The function `task_suspend' increments the task's suspend count and
+     stops all threads in the task.  As long as the suspend count is
+     positive newly created threads will not run.  This call does not
+     return until all threads are suspended.
+
+     The count may become greater than one, with the effect that it
+     will take more than one resume call to restart the task.
+
+     The function returns `KERN_SUCCESS' if the task has been suspended
+     and `KERN_INVALID_ARGUMENT' if TARGET_TASK is not a task.
+
+ -- Function: kern_return_t task_resume (task_t TARGET_TASK)
+     The function `task_resume' decrements the task's suspend count.  If
+     it becomes zero, all threads with zero suspend counts in the task
+     are resumed.  The count may not become negative.
+
+     The function returns `KERN_SUCCESS' if the task has been resumed,
+     `KERN_FAILURE' if the suspend count is already at zero and
+     `KERN_INVALID_ARGUMENT' if TARGET_TASK is not a task.
+
+ -- Function: kern_return_t task_priority (task_t TASK, int PRIORITY,
+          boolean_t CHANGE_THREADS)
+     The priority of a task is used only for creation of new threads; a
+     new thread's priority is set to the enclosing task's priority.
+     `task_priority' changes this task priority.  It also sets the
+     priorities of all threads in the task to this new priority if
+     CHANGE_THREADS is `TRUE'.  Existing threads are not affected
+     otherwise.  If this priority change violates the maximum priority
+     of some threads, as many threads as possible will be changed and
+     an error code will be returned.
+
+     The function returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_ARGUMENT' if TASK is not a task, or PRIORITY is not
+     a valid priority and `KERN_FAILURE' if CHANGE_THREADS was `TRUE'
+     and the attempt to change the priority of at least one existing
+     thread failed because the new priority would have exceeded that
+     thread's maximum priority.
+
+ -- Function: kern_return_t task_ras_control (task_t TARGET_TASK,
+          vm_address_t START_PC, vm_address_t END_PC, int FLAVOR)
+     The function `task_ras_control' manipulates a task's set of
+     restartable atomic sequences.  If a sequence is installed, and any
+     thread in the task is preempted within the range
+     [START_PC,END_PC], then the thread is resumed at START_PC.  This
+     enables applications to build atomic sequences which, when
+     executed to completion, will have executed atomically.
+     Restartable atomic sequences are intended to be used on systems
+     that do not have hardware support for low-overhead atomic
+     primitives.
+
+     As a thread can be rolled-back, the code in the sequence should
+     have no side effects other than a final store at END_PC. The
+     kernel does not guarantee that the sequence is restartable.  It
+     assumes the application knows what it's doing.
+
+     A task may have a finite number of atomic sequences that is
+     defined at compile time.
+
+     The flavor specifices the particular operation that should be
+     applied to this restartable atomic sequence.  Possible values for
+     flavor can be:
+
+    `TASK_RAS_CONTROL_PURGE_ALL'
+          Remove all registered sequences for this task.
+
+    `TASK_RAS_CONTROL_PURGE_ONE'
+          Remove the named registered sequence for this task.
+
+    `TASK_RAS_CONTROL_PURGE_ALL_AND_INSTALL_ONE'
+          Atomically remove all registered sequences and install the
+          named sequence.
+
+    `TASK_RAS_CONTROL_INSTALL_ONE'
+          Install this sequence.
+
+     The function returns `KERN_SUCCESS' if the operation has been
+     performed, `KERN_INVALID_ADDRESS' if the START_PC or END_PC values
+     are not a valid address for the requested operation (for example,
+     it is invalid to purge a sequence that has not been registered),
+     `KERN_RESOURCE_SHORTAGE' if an attempt was made to install more
+     restartable atomic sequences for a task than can be supported by
+     the kernel, `KERN_INVALID_VALUE' if a bad flavor was specified,
+     `KERN_INVALID_ARGUMENT' if TARGET_TASK is not a task and
+     `KERN_FAILURE' if the call is not not supported on this
+     configuration.
+
+
+File: mach.info,  Node: Task Special Ports,  Next: Syscall Emulation,  Prev: Task Execution,  Up: Task Interface
+
+7.2.5 Task Special Ports
+------------------------
+
+ -- Function: kern_return_t task_get_special_port (task_t TASK,
+          int WHICH_PORT, mach_port_t *SPECIAL_PORT)
+     The function `task_get_special_port' returns send rights to one of
+     a set of special ports for the task specified by TASK.
+
+     The special ports associated with a task are the kernel port
+     (`TASK_KERNEL_PORT'), the bootstrap port (`TASK_BOOTSTRAP_PORT')
+     and the exception port (`TASK_EXCEPTION_PORT').  The bootstrap
+     port is a port to which a task may send a message requesting other
+     system service ports.  This port is not used by the kernel.  The
+     task's exception port is the port to which messages are sent by
+     the kernel when an exception occurs and the thread causing the
+     exception has no exception port of its own.
+
+     The following macros to call `task_get_special_port' for a specific
+     port are defined in `mach/task_special_ports.h':
+     `task_get_exception_port' and `task_get_bootstrap_port'.
+
+     The function returns `KERN_SUCCESS' if the port was returned and
+     `KERN_INVALID_ARGUMENT' if TASK is not a task or WHICH_PORT is an
+     invalid port selector.
+
+ -- Function: kern_return_t task_get_kernel_port (task_t TASK,
+          mach_port_t *KERNEL_PORT)
+     The function `task_get_kernel_port' is equivalent to the function
+     `task_get_special_port' with the WHICH_PORT argument set to
+     `TASK_KERNEL_PORT'.
+
+ -- Function: kern_return_t task_get_exception_port (task_t TASK,
+          mach_port_t *EXCEPTION_PORT)
+     The function `task_get_exception_port' is equivalent to the
+     function `task_get_special_port' with the WHICH_PORT argument set
+     to `TASK_EXCEPTION_PORT'.
+
+ -- Function: kern_return_t task_get_bootstrap_port (task_t TASK,
+          mach_port_t *BOOTSTRAP_PORT)
+     The function `task_get_bootstrap_port' is equivalent to the
+     function `task_get_special_port' with the WHICH_PORT argument set
+     to `TASK_BOOTSTRAP_PORT'.
+
+ -- Function: kern_return_t task_set_special_port (task_t TASK,
+          int WHICH_PORT, mach_port_t SPECIAL_PORT)
+     The function `thread_set_special_port' sets one of a set of special
+     ports for the task specified by TASK.
+
+     The special ports associated with a task are the kernel port
+     (`TASK_KERNEL_PORT'), the bootstrap port (`TASK_BOOTSTRAP_PORT')
+     and the exception port (`TASK_EXCEPTION_PORT').  The bootstrap
+     port is a port to which a thread may send a message requesting
+     other system service ports.  This port is not used by the kernel.
+     The task's exception port is the port to which messages are sent
+     by the kernel when an exception occurs and the thread causing the
+     exception has no exception port of its own.
+
+     The function returns `KERN_SUCCESS' if the port was set and
+     `KERN_INVALID_ARGUMENT' if TASK is not a task or WHICH_PORT is an
+     invalid port selector.
+
+ -- Function: kern_return_t task_set_kernel_port (task_t TASK,
+          mach_port_t KERNEL_PORT)
+     The function `task_set_kernel_port' is equivalent to the function
+     `task_set_special_port' with the WHICH_PORT argument set to
+     `TASK_KERNEL_PORT'.
+
+ -- Function: kern_return_t task_set_exception_port (task_t TASK,
+          mach_port_t EXCEPTION_PORT)
+     The function `task_set_exception_port' is equivalent to the
+     function `task_set_special_port' with the WHICH_PORT argument set
+     to `TASK_EXCEPTION_PORT'.
+
+ -- Function: kern_return_t task_set_bootstrap_port (task_t TASK,
+          mach_port_t BOOTSTRAP_PORT)
+     The function `task_set_bootstrap_port' is equivalent to the
+     function `task_set_special_port' with the WHICH_PORT argument set
+     to `TASK_BOOTSTRAP_PORT'.
+
+
+File: mach.info,  Node: Syscall Emulation,  Prev: Task Special Ports,  Up: Task Interface
+
+7.2.6 Syscall Emulation
+-----------------------
+
+ -- Function: kern_return_t task_get_emulation_vector (task_t TASK,
+          int *VECTOR_START, emulation_vector_t *EMULATION_VECTOR,
+          mach_msg_type_number_t *EMULATION_VECTOR_COUNT)
+     The function `task_get_emulation_vector' gets the user-level
+     handler entry points for all emulated system calls.
+
+ -- Function: kern_return_t task_set_emulation_vector (task_t TASK,
+          int VECTOR_START, emulation_vector_t EMULATION_VECTOR,
+          mach_msg_type_number_t EMULATION_VECTOR_COUNT)
+     The function `task_set_emulation_vector' establishes user-level
+     handlers for the specified system calls.  Non-emulated system
+     calls are specified with an entry of `EML_ROUTINE_NULL'.  System
+     call emulation handlers are inherited by the childs of TASK.
+
+ -- Function: kern_return_t task_set_emulation (task_t TASK,
+          vm_address_t ROUTINE_ENTRY_PT, int ROUTINE_NUMBER)
+     The function `task_set_emulation' establishes a user-level handler
+     for the specified system call.  System call emulation handlers are
+     inherited by the childs of TASK.
+
+
+File: mach.info,  Node: Profiling,  Prev: Task Interface,  Up: Threads and Tasks
+
+7.3 Profiling
+=============
+
+ -- Function: kern_return_t task_enable_pc_sampling (task_t TASK,
+          int *TICKS, sampled_pc_flavor_t FLAVOR)
+ -- Function: kern_return_t thread_enable_pc_sampling (thread_t THREAD,
+          int *TICKS, sampled_pc_flavor_t FLAVOR)
+     The function `task_enable_pc_sampling' enables PC sampling for
+     TASK, the function `thread_enable_pc_sampling' enables PC sampling
+     for THREAD.  The kernel's idea of clock granularity is returned in
+     TICKS in usecs. (this value should not be trusted).  The sampling
+     flavor is specified by FLAVOR.
+
+     The function returns `KERN_SUCCESS' if the operation is completed
+     successfully and `KERN_INVALID_ARGUMENT' if THREAD is not a valid
+     thread.
+
+ -- Function: kern_return_t task_disable_pc_sampling (task_t TASK,
+          int *SAMPLE_COUNT)
+ -- Function: kern_return_t thread_disable_pc_sampling
+          (thread_t THREAD, int *SAMPLE_COUNT)
+     The function `task_disable_pc_sampling' disables PC sampling for
+     TASK, the function `thread_disable_pc_sampling' disables PC
+     sampling for THREAD.  The number of sample elements in the kernel
+     for the thread is returned in SAMPLE_COUNT.
+
+     The function returns `KERN_SUCCESS' if the operation is completed
+     successfully and `KERN_INVALID_ARGUMENT' if THREAD is not a valid
+     thread.
+
+ -- Function: kern_return_t task_get_sampled_pcs (task_t TASK,
+          sampled_pc_seqno_t *SEQNO, sampled_pc_array_t SAMPLED_PCS,
+          mach_msg_type_number_t *SAMPLE_COUNT)
+ -- Function: kern_return_t thread_get_sampled_pcs (thread_t THREAD,
+          sampled_pc_seqno_t *SEQNO, sampled_pc_array_t SAMPLED_PCS,
+          int *SAMPLE_COUNT)
+     The function `task_get_sampled_pcs' extracts the PC samples for
+     TASK, the function `thread_get_sampled_pcs' extracts the PC
+     samples for THREAD.  SEQNO is the sequence number of the sampled
+     PCs.  This is useful for determining when a collector thread has
+     missed a sample.  The sampled PCs for the thread are returned in
+     SAMPLED_PCS.  SAMPLE_COUNT contains the number of sample elements
+     returned.
+
+     The function returns `KERN_SUCCESS' if the operation is completed
+     successfully, `KERN_INVALID_ARGUMENT' if THREAD is not a valid
+     thread and `KERN_FAILURE' if THREAD is not sampled.
+
+ -- Data type: sampled_pc_t
+     This structure is returned in SAMPLED_PCS by the
+     `thread_get_sampled_pcs' and `task_get_sampled_pcs' functions and
+     provides pc samples for threads or tasks.  It has the following
+     members:
+
+    `natural_t id'
+          A thread-specific unique identifier.
+
+    `vm_offset_t pc'
+          A pc value.
+
+    `sampled_pc_flavor_t sampletype'
+          The type of the sample as per flavor.
+
+ -- Data type: sampled_pc_flavor_t
+     This data type specifies a pc sample flavor, either as argument
+     passed in FLAVOR to the `thread_enable_pc_sample' and
+     `thread_disable_pc_sample' functions, or as member `sampletype' in
+     the `sample_pc_t' data type.  The flavor is a bitwise-or of the
+     possible flavors defined in `mach/pc_sample.h':
+
+    `SAMPLED_PC_PERIODIC'
+          default
+
+    `SAMPLED_PC_VM_ZFILL_FAULTS'
+          zero filled fault
+
+    `SAMPLED_PC_VM_REACTIVATION_FAULTS'
+          reactivation fault
+
+    `SAMPLED_PC_VM_PAGEIN_FAULTS'
+          pagein fault
+
+    `SAMPLED_PC_VM_COW_FAULTS'
+          copy-on-write fault
+
+    `SAMPLED_PC_VM_FAULTS_ANY'
+          any fault
+
+    `SAMPLED_PC_VM_FAULTS'
+          the bitwise-or of `SAMPLED_PC_VM_ZFILL_FAULTS',
+          `SAMPLED_PC_VM_REACTIVATION_FAULTS',
+          `SAMPLED_PC_VM_PAGEIN_FAULTS' and `SAMPLED_PC_VM_COW_FAULTS'.
+
+
+File: mach.info,  Node: Host Interface,  Next: Processors and Processor Sets,  Prev: Threads and Tasks,  Up: Top
+
+8 Host Interface
+****************
+
+This section describes the Mach interface to a host executing a Mach
+kernel.  The interface allows to query statistics about a host and
+control its behaviour.
+
+   A host is represented by two ports, a name port HOST used to query
+information about the host accessible to everyone, and a control port
+HOST_PRIV used to manipulate it.  For example, you can query the
+current time using the name port, but to change the time you need to
+send a message to the host control port.
+
+   Everything described in this section is declared in the header file
+`mach.h'.
+
+* Menu:
+
+* Host Ports::                    Ports representing a host.
+* Host Information::              Retrieval of information about a host.
+* Host Time::                     Operations on the time as seen by a host.
+* Host Reboot::                   Rebooting the system.
+
+
+File: mach.info,  Node: Host Ports,  Next: Host Information,  Up: Host Interface
+
+8.1 Host Ports
+==============
+
+ -- Data type: host_t
+     This is a `mach_port_t' and used to hold the port name of a host
+     name port (or short: host port).  Any task can get a send right to
+     the name port of the host running the task using the
+     `mach_host_self' system call.  The name port can be used query
+     information about the host, for example the current time.
+
+ -- Function: host_t mach_host_self ()
+     The `mach_host_self' system call returns the calling thread's host
+     name port.  It has an effect equivalent to receiving a send right
+     for the host port.  `mach_host_self' returns the name of the send
+     right.  In particular, successive calls will increase the calling
+     task's user-reference count for the send right.
+
+     As a special exception, the kernel will overrun the user reference
+     count of the host name port, so that this function can not fail
+     for that reason.  Because of this, the user should not deallocate
+     the port right if an overrun might have happened.  Otherwise the
+     reference count could drop to zero and the send right be destroyed
+     while the user still expects to be able to use it.  As the kernel
+     does not make use of the number of extant send rights anyway, this
+     is safe to do (the host port itself is never destroyed).
+
+     The function returns `MACH_PORT_NULL' if a resource shortage
+     prevented the reception of the send right.
+
+     This function is also available in `mach/mach_traps.h'.
+
+ -- Data type: host_priv_t
+     This is a `mach_port_t' and used to hold the port name of a
+     privileged host control port.  A send right to the host control
+     port is inserted into the first task at bootstrap (*note
+     Modules::).  This is the only way to get access to the host
+     control port in Mach, so the initial task has to preserve the send
+     right carefully, moving a copy of it to other privileged tasks if
+     necessary and denying access to unprivileged tasks.
+
+
+File: mach.info,  Node: Host Information,  Next: Host Time,  Prev: Host Ports,  Up: Host Interface
+
+8.2 Host Information
+====================
+
+ -- Function: kern_return_t host_info (host_t HOST, int FLAVOR,
+          host_info_t HOST_INFO,
+          mach_msg_type_number_t *HOST_INFO_COUNT)
+     The `host_info' function returns various information about HOST.
+     HOST_INFO is an array of integers that is supplied by the caller.
+     It will be filled with the requested information.  HOST_INFO_COUNT
+     is supplied as the maximum number of integers in HOST_INFO.  On
+     return, it contains the actual number of integers in HOST_INFO.
+     The maximum number of integers returned by any flavor is
+     `HOST_INFO_MAX'.
+
+     The type of information returned is defined by FLAVOR, which can
+     be one of the following:
+
+    `HOST_BASIC_INFO'
+          The function returns basic information about the host, as
+          defined by `host_basic_info_t'.  This includes the number of
+          processors, their type, and the amount of memory installed in
+          the system.  The number of integers returned is
+          `HOST_BASIC_INFO_COUNT'.  For how to get more information
+          about the processor, see *Note Processor Interface::.
+
+    `HOST_PROCESSOR_SLOTS'
+          The function returns the numbers of the slots with active
+          processors in them.  The number of integers returned can be
+          up to `max_cpus', as returned by the `HOST_BASIC_INFO' flavor
+          of `host_info'.
+
+    `HOST_SCHED_INFO'
+          The function returns information of interest to schedulers as
+          defined by `host_sched_info_t'.  The number of integers
+          returned is `HOST_SCHED_INFO_COUNT'.
+
+     The function returns `KERN_SUCCESS' if the call succeeded and
+     `KERN_INVALID_ARGUMENT' if HOST is not a host or FLAVOR is not
+     recognized.  The function returns `MIG_ARRAY_TOO_LARGE' if the
+     returned info array is too large for HOST_INFO.  In this case,
+     HOST_INFO is filled as much as possible and HOST_INFO_COUNT is set
+     to the number of elements that would be returned if there were
+     enough room.
+
+ -- Data type: struct host_basic_info
+     A pointer to this structure is returned in HOST_INFO by the
+     `host_info' function and provides basic information about the host.
+     You can cast a variable of type `host_info_t' to a pointer of this
+     type if you provided it as the HOST_INFO parameter for the
+     `HOST_BASIC_INFO' flavor of `host_info'.  It has the following
+     members:
+
+    `int max_cpus'
+          The maximum number of possible processors for which the
+          kernel is configured.
+
+    `int avail_cpus'
+          The number of cpus currently available.
+
+    `vm_size_t memory_size'
+          The size of physical memory in bytes.
+
+    `cpu_type_t cpu_type'
+          The type of the master processor.
+
+    `cpu_subtype_t cpu_subtype'
+          The subtype of the master processor.
+
+     The type and subtype of the individual processors are also
+     available by `processor_info', see *Note Processor Interface::.
+
+ -- Data type: host_basic_info_t
+     This is a pointer to a `struct host_basic_info'.
+
+ -- Data type: struct host_sched_info
+     A pointer to this structure is returned in HOST_INFO by the
+     `host_info' function and provides information of interest to
+     schedulers.  You can cast a variable of type `host_info_t' to a
+     pointer of this type if you provided it as the HOST_INFO parameter
+     for the `HOST_SCHED_INFO' flavor of `host_info'.  It has the
+     following members:
+
+    `int min_timeout'
+          The minimum timeout and unit of time in milliseconds.
+
+    `int min_quantum'
+          The minimum quantum and unit of quantum in milliseconds.
+
+ -- Data type: host_sched_info_t
+     This is a pointer to a `struct host_sched_info'.
+
+ -- Function: kern_return_t host_kernel_version (host_t HOST,
+          kernel_version_t *VERSION)
+     The `host_kernel_version' function returns the version string
+     compiled into the kernel executing on HOST at the time it was
+     built in the character string VERSION.  This string describes the
+     version of the kernel.  The constant `KERNEL_VERSION_MAX' should be
+     used to dimension storage for the returned string if the
+     `kernel_version_t' declaration is not used.
+
+     If the version string compiled into the kernel is longer than
+     `KERNEL_VERSION_MAX', the result is truncated and not necessarily
+     null-terminated.
+
+     If HOST is not a valid send right to a host port, the function
+     returns `KERN_INVALID_ARGUMENT'.  If VERSION points to
+     inaccessible memory, it returns `KERN_INVALID_ADDRESS', and
+     `KERN_SUCCESS' otherwise.
+
+ -- Function: kern_return_t host_get_boot_info (host_priv_t HOST_PRIV,
+          kernel_boot_info_t BOOT_INFO)
+     The `host_get_boot_info' function returns the boot-time information
+     string supplied by the operator to the kernel executing on
+     HOST_PRIV in the character string BOOT_INFO.  The constant
+     `KERNEL_BOOT_INFO_MAX' should be used to dimension storage for the
+     returned string if the `kernel_boot_info_t' declaration is not
+     used.
+
+     If the boot-time information string supplied by the operator is
+     longer than `KERNEL_BOOT_INFO_MAX', the result is truncated and not
+     necessarily null-terminated.
+
+
+File: mach.info,  Node: Host Time,  Next: Host Reboot,  Prev: Host Information,  Up: Host Interface
+
+8.3 Host Time
+=============
+
+ -- Data type: time_value_t
+     This is the representation of a time in Mach.  It is a `struct
+     time_value' and consists of the following members:
+
+    `integer_t seconds'
+          The number of seconds.
+
+    `integer_t microseconds'
+          The number of microseconds.
+
+The number of microseconds should always be smaller than
+`TIME_MICROS_MAX' (100000).  A time with this property is "normalized".
+Normalized time values can be manipulated with the following macros:
+
+ -- Macro: time_value_add_usec (time_value_t *VAL, integer_t *MICROS)
+     Add MICROS microseconds to VAL.  If VAL is normalized and MICROS
+     smaller than `TIME_MICROS_MAX', VAL will be normalized afterwards.
+
+ -- Macro: time_value_add (time_value_t *RESULT, time_value_t *ADDEND)
+     Add the values in ADDEND to RESULT.  If both are normalized,
+     RESULT will be normalized afterwards.
+
+   A variable of type `time_value_t' can either represent a duration or
+a fixed point in time.  In the latter case, it shall be interpreted as
+the number of seconds and microseconds after the epoch 1. Jan 1970.
+
+ -- Function: kern_return_t host_get_time (host_t HOST,
+          time_value_t *CURRENT_TIME)
+     Get the current time as seen by HOST.  On success, the time passed
+     since the epoch is returned in CURRENT_TIME.
+
+ -- Function: kern_return_t host_set_time (host_priv_t HOST_PRIV,
+          time_value_t NEW_TIME)
+     Set the time of HOST_PRIV to NEW_TIME.
+
+ -- Function: kern_return_t host_adjust_time (host_priv_t HOST_PRIV,
+          time_value_t NEW_ADJUSTMENT, time_value_t *OLD_ADJUSTMENT)
+     Arrange for the current time as seen by HOST_PRIV to be gradually
+     changed by the adjustment value NEW_ADJUSTMENT, and return the old
+     adjustment value in OLD_ADJUSTMENT.
+
+   For efficiency, the current time is available through a mapped-time
+interface.
+
+ -- Data type: mapped_time_value_t
+     This structure defines the mapped-time interface.  It has the
+     following members:
+
+    `integer_t seconds'
+          The number of seconds.
+
+    `integer_t microseconds'
+          The number of microseconds.
+
+    `integer_t check_seconds'
+          This is a copy of the seconds value, which must be checked to
+          protect against a race condition when reading out the two
+          time values.
+
+   Here is an example how to read out the current time using the
+mapped-time interface:
+
+     do
+       {
+         secs = mtime->seconds;
+         usecs = mtime->microseconds;
+       }
+     while (secs != mtime->check_seconds);
+
+
+File: mach.info,  Node: Host Reboot,  Prev: Host Time,  Up: Host Interface
+
+8.4 Host Reboot
+===============
+
+ -- Function: kern_return_t host_reboot (host_priv_t HOST_PRIV,
+          int OPTIONS)
+     Reboot the host specified by HOST_PRIV.  The argument OPTIONS
+     specifies the flags.  The available flags are defined in
+     `sys/reboot.h':
+
+    `RB_HALT'
+          Do not reboot, but halt the machine.
+
+    `RB_DEBUGGER'
+          Do not reboot, but enter kernel debugger from user space.
+
+     If successful, the function might not return.
+
+
+File: mach.info,  Node: Processors and Processor Sets,  Next: Device Interface,  Prev: Host Interface,  Up: Top
+
+9 Processors and Processor Sets
+*******************************
+
+This section describes the Mach interface to processor sets and
+individual processors.  The interface allows to group processors into
+sets and control the processors and processor sets.
+
+   A processor is not a central part of the interface.  It is mostly of
+relevance as a part of a processor set.  Threads are always assigned to
+processor sets, and all processors in a set are equally involved in
+executing all threads assigned to that set.
+
+   The processor set is represented by two ports, a name port
+PROCESSOR_SET_NAME used to query information about the host accessible
+to everyone, and a control port PROCESSOR_SET used to manipulate it.
+
+* Menu:
+
+* Processor Set Interface::       How to work with processor sets.
+* Processor Interface::           How to work with individual processors.
+
+
+File: mach.info,  Node: Processor Set Interface,  Next: Processor Interface,  Up: Processors and Processor Sets
+
+9.1 Processor Set Interface
+===========================
+
+* Menu:
+
+* Processor Set Ports::           Ports representing a processor set.
+* Processor Set Access::          How the processor sets are accessed.
+* Processor Set Creation::        How new processor sets are created.
+* Processor Set Destruction::     How processor sets are destroyed.
+* Tasks and Threads on Sets::     Assigning tasks, threads to processor sets.
+* Processor Set Priority::        Specifying the priority of a processor set.
+* Processor Set Policy::          Changing the processor set policies.
+* Processor Set Info::            Obtaining information about a processor set.
+
+
+File: mach.info,  Node: Processor Set Ports,  Next: Processor Set Access,  Up: Processor Set Interface
+
+9.1.1 Processor Set Ports
+-------------------------
+
+ -- Data type: processor_set_name_t
+     This is a `mach_port_t' and used to hold the port name of a
+     processor set name port that names the processor set.  Any task
+     can get a send right to name port of a processor set.  The
+     processor set name port allows to get information about the
+     processor set.
+
+ -- Data type: processor_set_t
+     This is a `mach_port_t' and used to hold the port name of a
+     privileged processor set control port that represents the
+     processor set.  Operations on the processor set are implemented as
+     remote procedure calls to the processor set port.  The processor
+     set port allows to manipulate the processor set.
+
+
+File: mach.info,  Node: Processor Set Access,  Next: Processor Set Creation,  Prev: Processor Set Ports,  Up: Processor Set Interface
+
+9.1.2 Processor Set Access
+--------------------------
+
+ -- Function: kern_return_t host_processor_sets (host_t HOST,
+          processor_set_name_array_t *PROCESSOR_SETS,
+          mach_msg_type_number_t *PROCESSOR_SETS_COUNT)
+     The function `host_processor_sets' gets send rights to the name
+     port for each processor set currently assigned to HOST.
+
+     `host_processor_set_priv' can be used to obtain the control ports
+     from these if desired.  PROCESSOR_SETS is an array that is created
+     as a result of this call.  The caller may wish to `vm_deallocate'
+     this array when the data is no longer needed.
+     PROCESSOR_SETS_COUNT is set to the number of processor sets in the
+     PROCESSOR_SETS.
+
+     This function returns `KERN_SUCCESS' if the call succeeded and
+     `KERN_INVALID_ARGUMENT' if HOST is not a host.
+
+ -- Function: kern_return_t host_processor_set_priv
+          (host_priv_t HOST_PRIV, processor_set_name_t SET_NAME,
+          processor_set_t *SET)
+     The function `host_processor_set_priv' allows a privileged
+     application to obtain the control port SET for an existing
+     processor set from its name port SET_NAME.  The privileged host
+     port HOST_PRIV is required.
+
+     This function returns `KERN_SUCCESS' if the call succeeded and
+     `KERN_INVALID_ARGUMENT' if HOST_PRIV is not a valid host control
+     port.
+
+ -- Function: kern_return_t processor_set_default (host_t HOST,
+          processor_set_name_t *DEFAULT_SET)
+     The function `processor_set_default' returns the default processor
+     set of HOST in DEFAULT_SET.  The default processor set is used by
+     all threads, tasks, and processors that are not explicitly
+     assigned to other sets.  processor_set_default returns a port that
+     can be used to obtain information about this set (e.g. how many
+     threads are assigned to it).  This port cannot be used to perform
+     operations on that set.
+
+     This function returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_ARGUMENT' if HOST is not a host and
+     `KERN_INVALID_ADDRESS' if DEFAULT_SET points to inaccessible
+     memory.
+
+
+File: mach.info,  Node: Processor Set Creation,  Next: Processor Set Destruction,  Prev: Processor Set Access,  Up: Processor Set Interface
+
+9.1.3 Processor Set Creation
+----------------------------
+
+ -- Function: kern_return_t processor_set_create (host_t HOST,
+          processor_set_t *NEW_SET, processor_set_name_t *NEW_NAME)
+     The function `processor_set_create' creates a new processor set on
+     HOST and returns the two ports associated with it.  The port
+     returned in NEW_SET is the actual port representing the set.  It
+     is used to perform operations such as assigning processors, tasks,
+     or threads.  The port returned in NEW_NAME identifies the set, and
+     is used to obtain information about the set.
+
+     This function returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_ARGUMENT' if HOST is not a host,
+     `KERN_INVALID_ADDRESS' if NEW_SET or NEW_NAME points to
+     inaccessible memory and `KERN_FAILURE' is the operating system does
+     not support processor allocation.
+
+
+File: mach.info,  Node: Processor Set Destruction,  Next: Tasks and Threads on Sets,  Prev: Processor Set Creation,  Up: Processor Set Interface
+
+9.1.4 Processor Set Destruction
+-------------------------------
+
+ -- Function: kern_return_t processor_set_destroy
+          (processor_set_t PROCESSOR_SET)
+     The function `processor_set_destroy' destroys the specified
+     processor set.  Any assigned processors, tasks, or threads are
+     reassigned to the default set.  The object port for the processor
+     set is required (not the name port).  The default processor set
+     cannot be destroyed.
+
+     This function returns `KERN_SUCCESS' if the set was destroyed,
+     `KERN_FAILURE' if an attempt was made to destroy the default
+     processor set, or the operating system does not support processor
+     allocation, and `KERN_INVALID_ARGUMENT' if PROCESSOR_SET is not a
+     valid processor set control port.
+
+
+File: mach.info,  Node: Tasks and Threads on Sets,  Next: Processor Set Priority,  Prev: Processor Set Destruction,  Up: Processor Set Interface
+
+9.1.5 Tasks and Threads on Sets
+-------------------------------
+
+ -- Function: kern_return_t processor_set_tasks
+          (processor_set_t PROCESSOR_SET, task_array_t *TASK_LIST,
+          mach_msg_type_number_t *TASK_COUNT)
+     The function `processor_set_tasks' gets send rights to the kernel
+     port for each task currently assigned to PROCESSOR_SET.
+
+     TASK_LIST is an array that is created as a result of this call.
+     The caller may wish to `vm_deallocate' this array when the data is
+     no longer needed.  TASK_COUNT is set to the number of tasks in the
+     TASK_LIST.
+
+     This function returns `KERN_SUCCESS' if the call succeeded and
+     `KERN_INVALID_ARGUMENT' if PROCESSOR_SET is not a processor set.
+
+ -- Function: kern_return_t processor_set_threads
+          (processor_set_t PROCESSOR_SET, thread_array_t *THREAD_LIST,
+          mach_msg_type_number_t *THREAD_COUNT)
+     The function `processor_set_thread' gets send rights to the kernel
+     port for each thread currently assigned to PROCESSOR_SET.
+
+     THREAD_LIST is an array that is created as a result of this call.
+     The caller may wish to `vm_deallocate' this array when the data is
+     no longer needed.  THREAD_COUNT is set to the number of threads in
+     the THREAD_LIST.
+
+     This function returns `KERN_SUCCESS' if the call succeeded and
+     `KERN_INVALID_ARGUMENT' if PROCESSOR_SET is not a processor set.
+
+ -- Function: kern_return_t task_assign (task_t TASK,
+          processor_set_t PROCESSOR_SET, boolean_t ASSIGN_THREADS)
+     The function `task_assign' assigns TASK the set PROCESSOR_SET.
+     This assignment is for the purposes of determining the initial
+     assignment of newly created threads in task.  Any previous
+     assignment of the task is nullified.  Existing threads within the
+     task are also reassigned if ASSIGN_THREADS is `TRUE'.  They are
+     not affected if it is `FALSE'.
+
+     This function returns `KERN_SUCCESS' if the assignment has been
+     performed and `KERN_INVALID_ARGUMENT' if TASK is not a task, or
+     PROCESSOR_SET is not a processor set on the same host as TASK.
+
+ -- Function: kern_return_t task_assign_default (task_t TASK,
+          boolean_t ASSIGN_THREADS)
+     The function `task_assign_default' is a variant of `task_assign'
+     that assigns the task to the default processor set on that task's
+     host.  This variant exists because the control port for the
+     default processor set is privileged and not ususally available to
+     users.
+
+     This function returns `KERN_SUCCESS' if the assignment has been
+     performed and `KERN_INVALID_ARGUMENT' if TASK is not a task.
+
+ -- Function: kern_return_t task_get_assignment (task_t TASK,
+          processor_set_name_t *ASSIGNED_SET)
+     The function `task_get_assignment' returns the name of the
+     processor set to which the thread is currently assigned in
+     ASSIGNED_SET.  This port can only be used to obtain information
+     about the processor set.
+
+     This function returns `KERN_SUCCESS' if the assignment has been
+     performed, `KERN_INVALID_ADDRESS' if PROCESSOR_SET points to
+     inaccessible memory, and `KERN_INVALID_ARGUMENT' if TASK is not a
+     task.
+
+ -- Function: kern_return_t thread_assign (thread_t THREAD,
+          processor_set_t PROCESSOR_SET)
+     The function `thread_assign' assigns THREAD the set PROCESSOR_SET.
+     After the assignment is completed, the thread only executes on
+     processors assigned to the designated processor set.  If there are
+     no such processors, then the thread is unable to execute.  Any
+     previous assignment of the thread is nullified.  Unix system call
+     compatibility code may temporarily force threads to execute on the
+     master processor.
+
+     This function returns `KERN_SUCCESS' if the assignment has been
+     performed and `KERN_INVALID_ARGUMENT' if THREAD is not a thread,
+     or PROCESSOR_SET is not a processor set on the same host as THREAD.
+
+ -- Function: kern_return_t thread_assign_default (thread_t THREAD)
+     The function `thread_assign_default' is a variant of
+     `thread_assign' that assigns the thread to the default processor
+     set on that thread's host.  This variant exists because the
+     control port for the default processor set is privileged and not
+     ususally available to users.
+
+     This function returns `KERN_SUCCESS' if the assignment has been
+     performed and `KERN_INVALID_ARGUMENT' if THREAD is not a thread.
+
+ -- Function: kern_return_t thread_get_assignment (thread_t THREAD,
+          processor_set_name_t *ASSIGNED_SET)
+     The function `thread_get_assignment' returns the name of the
+     processor set to which the thread is currently assigned in
+     ASSIGNED_SET.  This port can only be used to obtain information
+     about the processor set.
+
+     This function returns `KERN_SUCCESS' if the assignment has been
+     performed, `KERN_INVALID_ADDRESS' if PROCESSOR_SET points to
+     inaccessible memory, and `KERN_INVALID_ARGUMENT' if THREAD is not
+     a thread.
+
+
+File: mach.info,  Node: Processor Set Priority,  Next: Processor Set Policy,  Prev: Tasks and Threads on Sets,  Up: Processor Set Interface
+
+9.1.6 Processor Set Priority
+----------------------------
+
+ -- Function: kern_return_t processor_set_max_priority
+          (processor_set_t PROCESSOR_SET, int MAX_PRIORITY,
+          boolean_t CHANGE_THREADS)
+     The function `processor_set_max_priority' is used to set the
+     maximum priority for a processor set.  The priority of a processor
+     set is used only for newly created threads (thread's maximum
+     priority is set to processor set's) and the assignment of threads
+     to the set (thread's maximum priority is reduced if it exceeds the
+     set's maximum priority, thread's priority is similarly reduced).
+     `processor_set_max_priority' changes this priority.  It also sets
+     the maximum priority of all threads assigned to the processor set
+     to this new priority if CHANGE_THREADS is `TRUE'.  If this maximum
+     priority is less than the priorities of any of these threads,
+     their priorities will also be set to this new value.
+
+     This function returns `KERN_SUCCESS' if the call succeeded and
+     `KERN_INVALID_ARGUMENT' if PROCESSOR_SET is not a processor set or
+     PRIORITY is not a valid priority.
+
+
+File: mach.info,  Node: Processor Set Policy,  Next: Processor Set Info,  Prev: Processor Set Priority,  Up: Processor Set Interface
+
+9.1.7 Processor Set Policy
+--------------------------
+
+ -- Function: kern_return_t processor_set_policy_enable
+          (processor_set_t PROCESSOR_SET, int POLICY)
+ -- Function: kern_return_t processor_set_policy_disable
+          (processor_set_t PROCESSOR_SET, int POLICY,
+          boolean_t CHANGE_THREADS)
+     Processor sets may restrict the scheduling policies to be used for
+     threads assigned to them.  These two calls provide the mechanism
+     for designating permitted and forbidden policies.  The current set
+     of permitted policies can be obtained from `processor_set_info'.
+     Timesharing may not be forbidden by any processor set.  This is a
+     compromise to reduce the complexity of the assign operation; any
+     thread whose policy is forbidden by the target processor set has
+     its policy reset to timesharing.  If the CHANGE_THREADS argument to
+     `processor_set_policy_disable' is true, threads currently assigned
+     to this processor set and using the newly disabled policy will have
+     their policy reset to timesharing.
+
+     `mach/policy.h' contains the allowed policies; it is included by
+     `mach.h'.  Not all policies (e.g. fixed priority) are supported by
+     all systems.
+
+     This function returns `KERN_SUCCESS' if the operation was completed
+     successfully and `KERN_INVALID_ARGUMENT' if PROCESSOR_SET is not a
+     processor set or POLICY is not a valid policy, or an attempt was
+     made to disable timesharing.
+
+
+File: mach.info,  Node: Processor Set Info,  Prev: Processor Set Policy,  Up: Processor Set Interface
+
+9.1.8 Processor Set Info
+------------------------
+
+ -- Function: kern_return_t processor_set_info
+          (processor_set_name_t SET_NAME, int FLAVOR, host_t *HOST,
+          processor_set_info_t PROCESSOR_SET_INFO,
+          mach_msg_type_number_t *PROCESSOR_SET_INFO_COUNT)
+     The function `processor_set_info' returns the selected information
+     array for a processor set, as specified by FLAVOR.
+
+     HOST is set to the host on which the processor set resides.  This
+     is the non-privileged host port.
+
+     PROCESSOR_SET_INFO is an array of integers that is supplied by the
+     caller and returned filled with specified information.
+     PROCESSOR_SET_INFO_COUNT is supplied as the maximum number of
+     integers in PROCESSOR_SET_INFO.  On return, it contains the actual
+     number of integers in PROCESSOR_SET_INFO.  The maximum number of
+     integers returned by any flavor is `PROCESSOR_SET_INFO_MAX'.
+
+     The type of information returned is defined by FLAVOR, which can
+     be one of the following:
+
+    `PROCESSOR_SET_BASIC_INFO'
+          The function returns basic information about the processor
+          set, as defined by `processor_set_basic_info_t'.  This
+          includes the number of tasks and threads assigned to the
+          processor set.  The number of integers returned is
+          `PROCESSOR_SET_BASIC_INFO_COUNT'.
+
+    `PROCESSOR_SET_SCHED_INFO'
+          The function returns information about the schduling policy
+          for the processor set as defined by
+          `processor_set_sched_info_t'.  The number of integers
+          returned is `PROCESSOR_SET_SCHED_INFO_COUNT'.
+
+     Some machines may define additional (machine-dependent) flavors.
+
+     The function returns `KERN_SUCCESS' if the call succeeded and
+     `KERN_INVALID_ARGUMENT' if PROCESSOR_SET is not a processor set or
+     FLAVOR is not recognized.  The function returns
+     `MIG_ARRAY_TOO_LARGE' if the returned info array is too large for
+     PROCESSOR_SET_INFO.  In this case, PROCESSOR_SET_INFO is filled as
+     much as possible and PROCESSOR_SET_INFO_COUNT is set to the number
+     of elements that would have been returned if there were enough
+     room.
+
+ -- Data type: struct processor_set_basic_info
+     This structure is returned in PROCESSOR_SET_INFO by the
+     `processor_set_info' function and provides basic information about
+     the processor set.  You can cast a variable of type
+     `processor_set_info_t' to a pointer of this type if you provided it
+     as the PROCESSOR_SET_INFO parameter for the
+     `PROCESSOR_SET_BASIC_INFO' flavor of `processor_set_info'.  It has
+     the following members:
+
+    `int processor_count'
+          number of processors
+
+    `int task_count'
+          number of tasks
+
+    `int thread_count'
+          number of threads
+
+    `int load_average'
+          scaled load average
+
+    `int mach_factor'
+          scaled mach factor
+
+ -- Data type: processor_set_basic_info_t
+     This is a pointer to a `struct processor_set_basic_info'.
+
+ -- Data type: struct processor_set_sched_info
+     This structure is returned in PROCESSOR_SET_INFO by the
+     `processor_set_info' function and provides schedule information
+     about the processor set.  You can cast a variable of type
+     `processor_set_info_t' to a pointer of this type if you provided it
+     as the PROCESSOR_SET_INFO parameter for the
+     `PROCESSOR_SET_SCHED_INFO' flavor of `processor_set_info'.  It has
+     the following members:
+
+    `int policies'
+          allowed policies
+
+    `int max_priority'
+          max priority for new threads
+
+ -- Data type: processor_set_sched_info_t
+     This is a pointer to a `struct processor_set_sched_info'.
+
+
+File: mach.info,  Node: Processor Interface,  Prev: Processor Set Interface,  Up: Processors and Processor Sets
+
+9.2 Processor Interface
+=======================
+
+ -- Data type: processor_t
+     This is a `mach_port_t' and used to hold the port name of a
+     processor port that represents the processor.  Operations on the
+     processor are implemented as remote procedure calls to the
+     processor port.
+
+* Menu:
+
+* Hosted Processors::             Getting a list of all processors on a host.
+* Processor Control::             Starting, stopping, controlling processors.
+* Processors and Sets::           Combining processors into processor sets.
+* Processor Info::                Obtaining information on processors.
+
+
+File: mach.info,  Node: Hosted Processors,  Next: Processor Control,  Up: Processor Interface
+
+9.2.1 Hosted Processors
+-----------------------
+
+ -- Function: kern_return_t host_processors (host_priv_t HOST_PRIV,
+          processor_array_t *PROCESSOR_LIST,
+          mach_msg_type_number_t *PROCESSOR_COUNT)
+     The function `host_processors' gets send rights to the processor
+     port for each processor existing on HOST_PRIV.  This is the
+     privileged port that allows its holder to control a processor.
+
+     PROCESSOR_LIST is an array that is created as a result of this
+     call.  The caller may wish to `vm_deallocate' this array when the
+     data is no longer needed.  PROCESSOR_COUNT is set to the number of
+     processors in the PROCESSOR_LIST.
+
+     This function returns `KERN_SUCCESS' if the call succeeded,
+     `KERN_INVALID_ARGUMENT' if HOST_PRIV is not a privileged host
+     port, and `KERN_INVALID_ADDRESS' if PROCESSOR_COUNT points to
+     inaccessible memory.
+
+
+File: mach.info,  Node: Processor Control,  Next: Processors and Sets,  Prev: Hosted Processors,  Up: Processor Interface
+
+9.2.2 Processor Control
+-----------------------
+
+ -- Function: kern_return_t processor_start (processor_t PROCESSOR)
+ -- Function: kern_return_t processor_exit (processor_t PROCESSOR)
+ -- Function: kern_return_t processor_control (processor_t PROCESSOR,
+          processor_info_t *CMD, mach_msg_type_number_t COUNT)
+     Some multiprocessors may allow privileged software to control
+     processors.  The `processor_start', `processor_exit', and
+     `processor_control' operations implement this.  The interpretation
+     of the command in CMD is machine dependent.  A newly started
+     processor is assigned to the default processor set.  An exited
+     processor is removed from the processor set to which it was
+     assigned and ceases to be active.
+
+     COUNT contains the length of the command CMD as a number of ints.
+
+     Availability limited.  All of these operations are
+     machine-dependent.  They may do nothing.  The ability to restart
+     an exited processor is also machine-dependent.
+
+     This function returns `KERN_SUCCESS' if the operation was
+     performed, `KERN_FAILURE' if the operation was not performed (a
+     likely reason is that it is not supported on this processor),
+     `KERN_INVALID_ARGUMENT' if PROCESSOR is not a processor, and
+     `KERN_INVALID_ADDRESS' if CMD points to inaccessible memory.
+
+
+File: mach.info,  Node: Processors and Sets,  Next: Processor Info,  Prev: Processor Control,  Up: Processor Interface
+
+9.2.3 Processors and Sets
+-------------------------
+
+ -- Function: kern_return_t processor_assign (processor_t PROCESSOR,
+          processor_set_t PROCESSOR_SET, boolean_t WAIT)
+     The function `processor_assign' assigns PROCESSOR to the the set
+     PROCESSOR_SET.  After the assignment is completed, the processor
+     only executes threads that are assigned to that processor set.
+     Any previous assignment of the processor is nullified.  The master
+     processor cannot be reassigned.  All processors take clock
+     interrupts at all times.  The WAIT argument indicates whether the
+     caller should wait for the assignment to be completed or should
+     return immediately.  Dedicated kernel threads are used to perform
+     processor assignment, so setting wait to `FALSE' allows assignment
+     requests to be queued and performed faster, especially if the
+     kernel has more than one dedicated internal thread for processor
+     assignment.  Redirection of other device interrupts away from
+     processors assigned to other than the default processor set is
+     machine-dependent.  Intermediaries that interpose on ports must be
+     sure to interpose on both ports involved in this call if they
+     interpose on either.
+
+     This function returns `KERN_SUCCESS' if the assignment has been
+     performed, `KERN_INVALID_ARGUMENT' if PROCESSOR is not a
+     processor, or PROCESSOR_SET is not a processor set on the same
+     host as PROCESSOR.
+
+ -- Function: kern_return_t processor_get_assignment
+          (processor_t PROCESSOR, processor_set_name_t *ASSIGNED_SET)
+     The function `processor_get_assignment' obtains the current
+     assignment of a processor.  The name port of the processor set is
+     returned in ASSIGNED_SET.
+
+
+File: mach.info,  Node: Processor Info,  Prev: Processors and Sets,  Up: Processor Interface
+
+9.2.4 Processor Info
+--------------------
+
+ -- Function: kern_return_t processor_info (processor_t PROCESSOR,
+          int FLAVOR, host_t *HOST, processor_info_t PROCESSOR_INFO,
+          mach_msg_type_number_t *PROCESSOR_INFO_COUNT)
+     The function `processor_info' returns the selected information
+     array for a processor, as specified by FLAVOR.
+
+     HOST is set to the host on which the processor set resides.  This
+     is the non-privileged host port.
+
+     PROCESSOR_INFO is an array of integers that is supplied by the
+     caller and returned filled with specified information.
+     PROCESSOR_INFO_COUNT is supplied as the maximum number of integers
+     in PROCESSOR_INFO.  On return, it contains the actual number of
+     integers in PROCESSOR_INFO.  The maximum number of integers
+     returned by any flavor is `PROCESSOR_INFO_MAX'.
+
+     The type of information returned is defined by FLAVOR, which can
+     be one of the following:
+
+    `PROCESSOR_BASIC_INFO'
+          The function returns basic information about the processor,
+          as defined by `processor_basic_info_t'.  This includes the
+          slot number of the processor.  The number of integers
+          returned is `PROCESSOR_BASIC_INFO_COUNT'.
+
+     Machines which require more configuration information beyond the
+     slot number are expected to define additional (machine-dependent)
+     flavors.
+
+     The function returns `KERN_SUCCESS' if the call succeeded and
+     `KERN_INVALID_ARGUMENT' if PROCESSOR is not a processor or FLAVOR
+     is not recognized.  The function returns `MIG_ARRAY_TOO_LARGE' if
+     the returned info array is too large for PROCESSOR_INFO.  In this
+     case, PROCESSOR_INFO is filled as much as possible and
+     PROCESSOR_INFOCNT is set to the number of elements that would have
+     been returned if there were enough room.
+
+ -- Data type: struct processor_basic_info
+     This structure is returned in PROCESSOR_INFO by the
+     `processor_info' function and provides basic information about the
+     processor.  You can cast a variable of type `processor_info_t' to a
+     pointer of this type if you provided it as the PROCESSOR_INFO
+     parameter for the `PROCESSOR_BASIC_INFO' flavor of
+     `processor_info'.  It has the following members:
+
+    `cpu_type_t cpu_type'
+          cpu type
+
+    `cpu_subtype_t cpu_subtype'
+          cpu subtype
+
+    `boolean_t running'
+          is processor running?
+
+    `int slot_num'
+          slot number
+
+    `boolean_t is_master'
+          is this the master processor
+
+ -- Data type: processor_basic_info_t
+     This is a pointer to a `struct processor_basic_info'.
+
+
+File: mach.info,  Node: Device Interface,  Next: Kernel Debugger,  Prev: Processors and Processor Sets,  Up: Top
+
+10 Device Interface
+*******************
+
+The GNU Mach microkernel provides a simple device interface that allows
+the user space programs to access the underlying hardware devices.  Each
+device has a unique name, which is a string up to 127 characters long.
+To open a device, the device master port has to be supplied.  The device
+master port is only available through the bootstrap port.  Anyone who
+has control over the device master port can use all hardware devices.
+
+ -- Data type: device_t
+     This is a `mach_port_t' and used to hold the port name of a device
+     port that represents the device.  Operations on the device are
+     implemented as remote procedure calls to the device port.  Each
+     device provides a sequence of records.  The length of a record is
+     specific to the device.  Data can be transferred "out-of-line" or
+     "in-line" (*note Memory::).
+
+   All constants and functions in this chapter are defined in
+`device/device.h'.
+
+* Menu:
+
+* Device Reply Server::           Handling device reply messages.
+* Device Open::                   Opening hardware devices.
+* Device Close::                  Closing hardware devices.
+* Device Read::                   Reading data from the device.
+* Device Write::                  Writing data to the device.
+* Device Map::                    Mapping devices into virtual memory.
+* Device Status::                 Querying and manipulating a device.
+* Device Filter::                 Filtering packets arriving on a device.
+
+
+File: mach.info,  Node: Device Reply Server,  Next: Device Open,  Up: Device Interface
+
+10.1 Device Reply Server
+========================
+
+Beside the usual synchronous interface, an asynchronous interface is
+provided.  For this, the caller has to receive and handle the reply
+messages seperately from the function call.
+
+ -- Function: boolean_t device_reply_server (msg_header_t *IN_MSG,
+          msg_header_t *OUT_MSG)
+     The function `device_reply_server' is produced by the remote
+     procedure call generator to handle a received message.  This
+     function does all necessary argument handling, and actually calls
+     one of the following functions: `ds_device_open_reply',
+     `ds_device_read_reply', `ds_device_read_reply_inband',
+     `ds_device_write_reply' and `ds_device_write_reply_inband'.
+
+     The IN_MSG argument is the message that has been received from the
+     kernel.  The OUT_MSG is a reply message, but this is not used for
+     this server.
+
+     The function returns `TRUE' to indicate that the message in
+     question was applicable to this interface, and that the appropriate
+     routine was called to interpret the message.  It returns `FALSE' to
+     indicate that the message did not apply to this interface, and
+     that no other action was taken.
+
+
+File: mach.info,  Node: Device Open,  Next: Device Close,  Prev: Device Reply Server,  Up: Device Interface
+
+10.2 Device Open
+================
+
+ -- Function: kern_return_t device_open (mach_port_t MASTER_PORT,
+          dev_mode_t MODE, dev_name_t NAME, device_t *DEVICE)
+     The function `device_open' opens the device NAME and returns a
+     port to it in DEVICE.  The open count for the device is
+     incremented by one.  If the open count was 0, the open handler for
+     the device is invoked.
+
+     MASTER_PORT must hold the master device port.  NAME specifies the
+     device to open, and is a string up to 128 characters long.  MODE
+     is the open mode.  It is a bitwise-or of the following constants:
+
+    `D_READ'
+          Request read access for the device.
+
+    `D_WRITE'
+          Request write access for the device.
+
+    `D_NODELAY'
+          Do not delay an open.
+
+     The function returns `D_SUCCESS' if the device was successfully
+     opened, `D_INVALID_OPERATION' if MASTER_PORT is not the master
+     device port, `D_WOULD_BLOCK' is the device is busy and `D_NOWAIT'
+     was specified in mode, `D_ALREADY_OPEN' if the device is already
+     open in an incompatible mode and `D_NO_SUCH_DEVICE' if NAME does
+     not denote a know device.
+
+ -- Function: kern_return_t device_open_request
+          (mach_port_t MASTER_PORT, mach_port_t REPLY_PORT,
+          dev_mode_t MODE, dev_name_t NAME)
+ -- Function: kern_return_t ds_device_open_reply
+          (mach_port_t REPLY_PORT, kern_return_t RETURN,
+          device_t *DEVICE)
+     This is the asynchronous form of the `device_open' function.
+     `device_open_request' performs the open request.  The meaning for
+     the parameters is as in `device_open'.  Additionally, the caller
+     has to supply a reply port to which the `ds_device_open_reply'
+     message is sent by the kernel when the open has been performed.
+     The return value of the open operation is stored in RETURN_CODE.
+
+     As neither function receives a reply message, only message
+     transmission errors apply.  If no error occurs, `KERN_SUCCESS' is
+     returned.
+
+
+File: mach.info,  Node: Device Close,  Next: Device Read,  Prev: Device Open,  Up: Device Interface
+
+10.3 Device Close
+=================
+
+ -- Function: kern_return_t device_close (device_t DEVICE)
+     The function `device_close' decrements the open count of the device
+     by one.  If the open count drops to zero, the close handler for the
+     device is called.  The device to close is specified by its port
+     DEVICE.
+
+     The function returns `D_SUCCESS' if the device was successfully
+     closed and `D_NO_SUCH_DEVICE' if DEVICE does not denote a device
+     port.
+
+
+File: mach.info,  Node: Device Read,  Next: Device Write,  Prev: Device Close,  Up: Device Interface
+
+10.4 Device Read
+================
+
+ -- Function: kern_return_t device_read (device_t DEVICE,
+          dev_mode_t MODE, recnum_t RECNUM, int BYTES_WANTED,
+          io_buf_ptr_t *DATA, mach_msg_type_number_t *DATA_COUNT)
+     The function `device_read' reads BYTES_WANTED bytes from DEVICE,
+     and stores them in a buffer allocated with `vm_allocate', which
+     address is returned in DATA.  The caller must deallocated it if it
+     is no longer needed.  The number of bytes actually returned is
+     stored in DATA_COUNT.
+
+     If MODE is `D_NOWAIT', the operation does not block.  Otherwise
+     MODE should be 0.  RECNUM is the record number to be read, its
+     meaning is device specific.
+
+     The function returns `D_SUCCESS' if some data was successfully
+     read, `D_WOULD_BLOCK' if no data is currently available and
+     `D_NOWAIT' is specified, and `D_NO_SUCH_DEVICE' if DEVICE does not
+     denote a device port.
+
+ -- Function: kern_return_t device_read_inband (device_t DEVICE,
+          dev_mode_t MODE, recnum_t RECNUM, int BYTES_WANTED,
+          io_buf_ptr_inband_t *DATA, mach_msg_type_number_t *DATA_COUNT)
+     The `device_read_inband' function works as the `device_read'
+     function, except that the data is returned "in-line" in the reply
+     IPC message (*note Memory::).
+
+ -- Function: kern_return_t device_read_request (device_t DEVICE,
+          mach_port_t REPLY_PORT, dev_mode_t MODE, recnum_t RECNUM,
+          int BYTES_WANTED)
+ -- Function: kern_return_t ds_device_read_reply
+          (mach_port_t REPLY_PORT, kern_return_t RETURN_CODE,
+          io_buf_ptr_t DATA, mach_msg_type_number_t DATA_COUNT)
+     This is the asynchronous form of the `device_read' function.
+     `device_read_request' performs the read request.  The meaning for
+     the parameters is as in `device_read'.  Additionally, the caller
+     has to supply a reply port to which the `ds_device_read_reply'
+     message is sent by the kernel when the read has been performed.
+     The return value of the read operation is stored in RETURN_CODE.
+
+     As neither function receives a reply message, only message
+     transmission errors apply.  If no error occurs, `KERN_SUCCESS' is
+     returned.
+
+ -- Function: kern_return_t device_read_request_inband
+          (device_t DEVICE, mach_port_t REPLY_PORT, dev_mode_t MODE,
+          recnum_t RECNUM, int BYTES_WANTED)
+ -- Function: kern_return_t ds_device_read_reply_inband
+          (mach_port_t REPLY_PORT, kern_return_t RETURN_CODE,
+          io_buf_ptr_t DATA, mach_msg_type_number_t DATA_COUNT)
+     The `device_read_request_inband' and `ds_device_read_reply_inband'
+     functions work as the `device_read_request' and
+     `ds_device_read_reply' functions, except that the data is returned
+     "in-line" in the reply IPC message (*note Memory::).
+
+
+File: mach.info,  Node: Device Write,  Next: Device Map,  Prev: Device Read,  Up: Device Interface
+
+10.5 Device Write
+=================
+
+ -- Function: kern_return_t device_write (device_t DEVICE,
+          dev_mode_t MODE, recnum_t RECNUM, io_buf_ptr_t DATA,
+          mach_msg_type_number_t DATA_COUNT, int *BYTES_WRITTEN)
+     The function `device_write' writes DATA_COUNT bytes from the
+     buffer DATA to DEVICE.  The number of bytes actually written is
+     returned in BYTES_WRITTEN.
+
+     If MODE is `D_NOWAIT', the function returns without waiting for
+     I/O completion.  Otherwise MODE should be 0.  RECNUM is the record
+     number to be written, its meaning is device specific.
+
+     The function returns `D_SUCCESS' if some data was successfully
+     written and `D_NO_SUCH_DEVICE' if DEVICE does not denote a device
+     port or the device is dead or not completely open.
+
+ -- Function: kern_return_t device_write_inband (device_t DEVICE,
+          dev_mode_t MODE, recnum_t RECNUM, int BYTES_WANTED,
+          io_buf_ptr_inband_t *DATA, mach_msg_type_number_t *DATA_COUNT)
+     The `device_write_inband' function works as the `device_write'
+     function, except that the data is sent "in-line" in the request IPC
+     message (*note Memory::).
+
+ -- Function: kern_return_t device_write_request (device_t DEVICE,
+          mach_port_t REPLY_PORT, dev_mode_t MODE, recnum_t RECNUM,
+          io_buf_ptr_t DATA, mach_msg_type_number_t DATA_COUNT)
+ -- Function: kern_return_t ds_device_write_reply
+          (mach_port_t REPLY_PORT, kern_return_t RETURN_CODE,
+          int BYTES_WRITTEN)
+     This is the asynchronous form of the `device_write' function.
+     `device_write_request' performs the write request.  The meaning for
+     the parameters is as in `device_write'.  Additionally, the caller
+     has to supply a reply port to which the `ds_device_write_reply'
+     message is sent by the kernel when the write has been performed.
+     The return value of the write operation is stored in RETURN_CODE.
+
+     As neither function receives a reply message, only message
+     transmission errors apply.  If no error occurs, `KERN_SUCCESS' is
+     returned.
+
+ -- Function: kern_return_t device_write_request_inband
+          (device_t DEVICE, mach_port_t REPLY_PORT, dev_mode_t MODE,
+          recnum_t RECNUM, io_buf_ptr_t DATA,
+          mach_msg_type_number_t DATA_COUNT)
+ -- Function: kern_return_t ds_device_write_reply_inband
+          (mach_port_t REPLY_PORT, kern_return_t RETURN_CODE,
+          int BYTES_WRITTEN)
+     The `device_write_request_inband' and
+     `ds_device_write_reply_inband' functions work as the
+     `device_write_request' and `ds_device_write_reply' functions,
+     except that the data is sent "in-line" in the request IPC message
+     (*note Memory::).
+
+
+File: mach.info,  Node: Device Map,  Next: Device Status,  Prev: Device Write,  Up: Device Interface
+
+10.6 Device Map
+===============
+
+ -- Function: kern_return_t device_map (device_t DEVICE,
+          vm_prot_t PROT, vm_offset_t OFFSET, vm_size_t SIZE,
+          mach_port_t *PAGER, int UNMAP)
+     The function `device_map' creates a new memory manager for DEVICE
+     and returns a port to it in PAGER.  The memory manager is usable
+     as a memory object in a `vm_map' call.  The call is device
+     dependant.
+
+     The protection for the memory object is specified by PROT.  The
+     memory object starts at OFFSET within the device and extends SIZE
+     bytes.  UNMAP is currently unused.
+
+     The function returns `D_SUCCESS' if some data was successfully
+     written and `D_NO_SUCH_DEVICE' if DEVICE does not denote a device
+     port or the device is dead or not completely open.
+
+
+File: mach.info,  Node: Device Status,  Next: Device Filter,  Prev: Device Map,  Up: Device Interface
+
+10.7 Device Status
+==================
+
+ -- Function: kern_return_t device_set_status (device_t DEVICE,
+          dev_flavor_t FLAVOR, dev_status_t STATUS,
+          mach_msg_type_number_t STATUS_COUNT)
+     The function `device_set_status' sets the status of a device.  The
+     possible values for FLAVOR and their interpretation is device
+     specific.
+
+     The function returns `D_SUCCESS' if some data was successfully
+     written and `D_NO_SUCH_DEVICE' if DEVICE does not denote a device
+     port or the device is dead or not completely open.
+
+ -- Function: kern_return_t device_get_status (device_t DEVICE,
+          dev_flavor_t FLAVOR, dev_status_t STATUS,
+          mach_msg_type_number_t *STATUS_COUNT)
+     The function `device_get_status' gets the status of a device.  The
+     possible values for FLAVOR and their interpretation is device
+     specific.
+
+     The function returns `D_SUCCESS' if some data was successfully
+     written and `D_NO_SUCH_DEVICE' if DEVICE does not denote a device
+     port or the device is dead or not completely open.
+
+
+File: mach.info,  Node: Device Filter,  Prev: Device Status,  Up: Device Interface
+
+10.8 Device Filter
+==================
+
+ -- Function: kern_return_t device_set_filter (device_t DEVICE,
+          mach_port_t RECEIVE_PORT,
+          mach_msg_type_name_t RECEIVE_PORT_TYPE, int PRIORITY,
+          filter_array_t FILTER, mach_msg_type_number_t FILTER_COUNT)
+     The function `device_set_filter' makes it possible to filter out
+     selected data arriving at the device and forward it to a port.
+     FILTER is a list of filter commands, which are applied to incoming
+     data to determine if the data should be sent to RECEIVE_PORT.  The
+     IPC type of the send right is specified by RECEIVE_PORT_RIGHT, it
+     is either `MACH_MSG_TYPE_MAKE_SEND' or `MACH_MSG_TYPE_MOVE_SEND'.
+     The PRIORITY value is used to order multiple filters.
+
+     There can be up to `NET_MAX_FILTER' commands in FILTER.  The
+     actual number of commands is passed in FILTER_COUNT.  For the
+     purpose of the filter test, an internal stack is provided.  After
+     all commands have been processed, the value on the top of the stack
+     determines if the data is forwarded or the next filter is tried.
+
+     Each word of the command list specifies a data (push) operation
+     (high order NETF_NBPO bits) as well as a binary operator (low
+     order NETF_NBPA bits).  The value to be pushed onto the stack is
+     chosen as follows.
+
+    `NETF_PUSHLIT'
+          Use the next short word of the filter as the value.
+
+    `NETF_PUSHZERO'
+          Use 0 as the value.
+
+    `NETF_PUSHWORD+N'
+          Use short word N of the "data" portion of the message as the
+          value.
+
+    `NETF_PUSHHDR+N'
+          Use short word N of the "header" portion of the message as
+          the value.
+
+    `NETF_PUSHIND+N'
+          Pops the top long word from the stack and then uses short
+          word N of the "data" portion of the message as the value.
+
+    `NETF_PUSHHDRIND+N'
+          Pops the top long word from the stack and then uses short
+          word N of the "header" portion of the message as the value.
+
+    `NETF_PUSHSTK+N'
+          Use long word N of the stack (where the top of stack is long
+          word 0) as the value.
+
+    `NETF_NOPUSH'
+          Don't push a value.
+
+     The unsigned value so chosen is promoted to a long word before
+     being pushed.  Once a value is pushed (except for the case of
+     `NETF_NOPUSH'), the top two long words of the stack are popped and
+     a binary operator applied to them (with the old top of stack as the
+     second operand).  The result of the operator is pushed on the
+     stack.  These operators are:
+
+    `NETF_NOP'
+          Don't pop off any values and do no operation.
+
+    `NETF_EQ'
+          Perform an equal comparison.
+
+    `NETF_LT'
+          Perform a less than comparison.
+
+    `NETF_LE'
+          Perform a less than or equal comparison.
+
+    `NETF_GT'
+          Perform a greater than comparison.
+
+    `NETF_GE'
+          Perform a greater than or equal comparison.
+
+    `NETF_AND'
+          Perform a bitise boolean AND operation.
+
+    `NETF_OR'
+          Perform a bitise boolean inclusive OR operation.
+
+    `NETF_XOR'
+          Perform a bitise boolean exclusive OR operation.
+
+    `NETF_NEQ'
+          Perform a not equal comparison.
+
+    `NETF_LSH'
+          Perform a left shift operation.
+
+    `NETF_RSH'
+          Perform a right shift operation.
+
+    `NETF_ADD'
+          Perform an addition.
+
+    `NETF_SUB'
+          Perform a subtraction.
+
+    `NETF_COR'
+          Perform an equal comparison. If the comparison is `TRUE',
+          terminate the filter list.  Otherwise, pop the result of the
+          comparison off the stack.
+
+    `NETF_CAND'
+          Perform an equal comparison. If the comparison is `FALSE',
+          terminate the filter list.  Otherwise, pop the result of the
+          comparison off the stack.
+
+    `NETF_CNOR'
+          Perform a not equal comparison. If the comparison is `FALSE',
+          terminate the filter list.  Otherwise, pop the result of the
+          comparison off the stack.
+
+    `NETF_CNAND'
+          Perform a not equal comparison. If the comparison is `TRUE',
+          terminate the filter list.  Otherwise, pop the result of the
+          comparison off the stack.  The scan of the filter list
+          terminates when the filter list is emptied, or a `NETF_C...'
+          operation terminates the list. At this time, if the final
+          value of the top of the stack is `TRUE', then the message is
+          accepted for the filter.
+
+     The function returns `D_SUCCESS' if some data was successfully
+     written, `D_INVALID_OPERATION' if RECEIVE_PORT is not a valid send
+     right, and `D_NO_SUCH_DEVICE' if DEVICE does not denote a device
+     port or the device is dead or not completely open.
+
+
+File: mach.info,  Node: Kernel Debugger,  Next: Copying,  Prev: Device Interface,  Up: Top
+
+11 Kernel Debugger
+******************
+
+The GNU Mach kernel debugger `ddb' is a powerful built-in debugger with
+a gdb like syntax.  It is enabled at compile time using the
+`--enable-kdb' option.  Whenever you want to enter the debugger while
+running the kernel, you can press the key combination <Ctrl-Alt-D>.
+
+* Menu:
+
+* Operation::                     Basic architecture of the kernel debugger.
+* Commands::                      Available commands in the kernel debugger.
+* Variables::                     Access of variables from the kernel debugger.
+* Expressions::                   Usage of expressions in the kernel debugger.
+
+
+File: mach.info,  Node: Operation,  Next: Commands,  Up: Kernel Debugger
+
+11.1 Operation
+==============
+
+The current location is called "dot".  The dot is displayed with a
+hexadecimal format at a prompt.  Examine and write commands update dot
+to the address of the last line examined or the last location modified,
+and set "next" to the address of the next location to be examined or
+changed.  Other commands don't change dot, and set next to be the same
+as dot.
+
+   The general command syntax is:
+
+     COMMAND[/MODIFIER] ADDRESS [,COUNT]
+
+   `!!' repeats the previous command, and a blank line repeats from the
+address next with count 1 and no modifiers.  Specifying ADDRESS sets
+dot to the address.  Omitting ADDRESS uses dot.  A missing COUNT is
+taken to be 1 for printing commands or infinity for stack traces.
+
+   Current `ddb' is enhanced to support multi-thread debugging.  A
+break point can be set only for a specific thread, and the address space
+or registers of non current thread can be examined or modified if
+supported by machine dependent routines.  For example,
+
+     break/t mach_msg_trap $task11.0
+
+   sets a break point at `mach_msg_trap' for the first thread of task
+11 listed by a `show all threads' command.
+
+   In the above example, `$task11.0' is translated to the corresponding
+thread structure's address by variable translation mechanism described
+later.  If a default target thread is set in a variable `$thread', the
+`$task11.0' can be omitted.  In general, if `t' is specified in a
+modifier of a command line, a specified thread or a default target
+thread is used as a target thread instead of the current one.  The `t'
+modifier in a command line is not valid in evaluating expressions in a
+command line.  If you want to get a value indirectly from a specific
+thread's address space or access to its registers within an expression,
+you have to specify a default target thread in advance, and to use `:t'
+modifier immediately after the indirect access or the register
+reference like as follows:
+
+     set $thread $task11.0
+     print $eax:t *(0x100):tuh
+
+   No sign extension and indirection `size(long, half word, byte)' can
+be specified with `u', `l', `h' and `b' respectively for the indirect
+access.
+
+   Note: Support of non current space/register access and user space
+break point depend on the machines.  If not supported, attempts of such
+operation may provide incorrect information or may cause strange
+behavior.  Even if supported, the user space access is limited to the
+pages resident in the main memory at that time.  If a target page is not
+in the main memory, an error will be reported.
+
+   `ddb' has a feature like a command `more' for the output.  If an
+output line exceeds the number set in the `$lines' variable, it
+displays `--db_more--' and waits for a response.  The valid responses
+for it are:
+
+`<SPC>'
+     one more page
+
+`<RET>'
+     one more line
+
+`q'
+     abort the current command, and return to the command input mode
+
diff --git a/doc/mach.info-2 b/doc/mach.info-2
new file mode 100644
index 00000000..806539f1
--- /dev/null
+++ b/doc/mach.info-2
@@ -0,0 +1,1663 @@
+This is ../doc/mach.info, produced by makeinfo version 4.8 from
+../doc/mach.texi.
+
+INFO-DIR-SECTION Kernel
+START-INFO-DIR-ENTRY
+* GNUMach: (mach).              Using and programming the GNU Mach microkernel.
+END-INFO-DIR-ENTRY
+
+   This file documents the GNU Mach microkernel.
+
+   This is Edition 0.4, last updated 2001-09-01, of `The GNU Mach
+Reference Manual', for Version 1.3.99.
+
+   Copyright (C) 2001 Free Software Foundation, Inc.
+
+   Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being "Free Software Needs Free Documentation" and
+"GNU Lesser General Public License", the Front-Cover texts being (a)
+(see below), and with the Back-Cover Texts being (b) (see below).  A
+copy of the license is included in the section entitled "GNU Free
+Documentation License".
+
+   (a) The FSF's Front-Cover Text is:
+
+   A GNU Manual
+
+   (b) The FSF's Back-Cover Text is:
+
+   You have freedom to copy and modify this GNU Manual, like GNU
+software.  Copies published by the Free Software Foundation raise
+funds for GNU development.
+
+   This work is based on manual pages under the following copyright and
+license:
+
+Mach Operating System
+Copyright (C) 1991,1990 Carnegie Mellon University
+All Rights Reserved.
+
+   Permission to use, copy, modify and distribute this software and its
+documentation is hereby granted, provided that both the copyright
+notice and this permission notice appear in all copies of the software,
+derivative works or modified versions, and any portions thereof, and
+that both notices appear in supporting documentation.
+
+   CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
+CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR ANY
+DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
+
+
+File: mach.info,  Node: Commands,  Next: Variables,  Prev: Operation,  Up: Kernel Debugger
+
+11.2 Commands
+=============
+
+`examine(x) [/MODIFIER] ADDR[,COUNT] [ THREAD ]'
+     Display the addressed locations according to the formats in the
+     modifier.  Multiple modifier formats display multiple locations.
+     If no format is specified, the last formats specified for this
+     command is used.  Address space other than that of the current
+     thread can be specified with `t' option in the modifier and THREAD
+     parameter.  The format characters are
+
+    `b'
+          look at by bytes(8 bits)
+
+    `h'
+          look at by half words(16 bits)
+
+    `l'
+          look at by long words(32 bits)
+
+    `a'
+          print the location being displayed
+
+    `,'
+          skip one unit producing no output
+
+    `A'
+          print the location with a line number if possible
+
+    `x'
+          display in unsigned hex
+
+    `z'
+          display in signed hex
+
+    `o'
+          display in unsigned octal
+
+    `d'
+          display in signed decimal
+
+    `u'
+          display in unsigned decimal
+
+    `r'
+          display in current radix, signed
+
+    `c'
+          display low 8 bits as a character.  Non-printing characters
+          are displayed as an octal escape code (e.g. '\000').
+
+    `s'
+          display the null-terminated string at the location.
+          Non-printing characters are displayed as octal escapes.
+
+    `m'
+          display in unsigned hex with character dump at the end of
+          each line.  The location is also displayed in hex at the
+          beginning of each line.
+
+    `i'
+          display as an instruction
+
+    `I'
+          display as an instruction with possible alternate formats
+          depending on the machine:
+
+         `vax'
+               don't assume that each external label is a procedure
+               entry mask
+
+         `i386'
+               don't round to the next long word boundary
+
+         `mips'
+               print register contents
+
+`xf'
+     Examine forward.  It executes an examine command with the last
+     specified parameters to it except that the next address displayed
+     by it is used as the start address.
+
+`xb'
+     Examine backward.  It executes an examine command with the last
+     specified parameters to it except that the last start address
+     subtracted by the size displayed by it is used as the start
+     address.
+
+`print[/axzodurc] ADDR1 [ ADDR2 ... ]'
+     Print ADDR's according to the modifier character.  Valid formats
+     are: `a' `x' `z' `o' `d' `u' `r' `c'.  If no modifier is
+     specified, the last one specified to it is used.  ADDR can be a
+     string, and it is printed as it is.  For example,
+
+          print/x "eax = " $eax "\necx = " $ecx "\n"
+
+     will print like
+
+          eax = xxxxxx
+          ecx = yyyyyy
+
+`write[/bhlt] ADDR [ THREAD ] EXPR1 [ EXPR2 ... ]'
+     Write the expressions at succeeding locations.  The write unit
+     size can be specified in the modifier with a letter b (byte), h
+     (half word) or l(long word) respectively.  If omitted, long word
+     is assumed.  Target address space can also be specified with `t'
+     option in the modifier and THREAD parameter.  Warning: since there
+     is no delimiter between expressions, strange things may happen.
+     It's best to enclose each expression in parentheses.
+
+`set $VARIABLE [=] EXPR'
+     Set the named variable or register with the value of EXPR.  Valid
+     variable names are described below.
+
+`break[/tuTU] ADDR[,COUNT] [ THREAD1 ... ]'
+     Set a break point at ADDR.  If count is supplied, continues
+     (COUNT-1) times before stopping at the break point.  If the break
+     point is set, a break point number is printed with `#'.  This
+     number can be used in deleting the break point or adding
+     conditions to it.
+
+    `t'
+          Set a break point only for a specific thread.  The thread is
+          specified by THREAD parameter, or default one is used if the
+          parameter is omitted.
+
+    `u'
+          Set a break point in user space address.  It may be combined
+          with `t' or `T' option to specify the non-current target user
+          space.  Without `u' option, the address is considered in the
+          kernel space, and wrong space address is rejected with an
+          error message.  This option can be used only if it is
+          supported by machine dependent routines.
+
+    `T'
+          Set a break point only for threads in a specific task.  It is
+          like `t' option except that the break point is valid for all
+          threads which belong to the same task as the specified target
+          thread.
+
+    `U'
+          Set a break point in shared user space address.  It is like
+          `u' option, except that the break point is valid for all
+          threads which share the same address space even if `t' option
+          is specified.  `t' option is used only to specify the target
+          shared space.  Without `t' option, `u' and `U' have the same
+          meanings.  `U' is useful for setting a user space break point
+          in non-current address space with `t' option such as in an
+          emulation library space.  This option can be used only if it
+          is supported by machine dependent routines.
+
+     Warning: if a user text is shadowed by a normal user space
+     debugger, user space break points may not work correctly.  Setting
+     a break point at the low-level code paths may also cause strange
+     behavior.
+
+`delete[/tuTU] ADDR|#NUMBER [ THREAD1 ... ]'
+     Delete the break point.  The target break point can be specified
+     by a break point number with `#', or by ADDR like specified in
+     `break' command.
+
+`cond #NUMBER [ CONDITION COMMANDS ]'
+     Set or delete a condition for the break point specified by the
+     NUMBER.  If the CONDITION and COMMANDS are null, the condition is
+     deleted.  Otherwise the condition is set for it.  When the break
+     point is hit, the CONDITION is evaluated.  The COMMANDS will be
+     executed if the condition is true and the break point count set by
+     a break point command becomes zero.  COMMANDS is a list of
+     commands separated by semicolons.  Each command in the list is
+     executed in that order, but if a `continue' command is executed,
+     the command execution stops there, and the stopped thread resumes
+     execution.  If the command execution reaches the end of the list,
+     and it enters into a command input mode.  For example,
+
+          set $work0 0
+          break/Tu xxx_start $task7.0
+          cond #1  (1)  set $work0 1; set $work1 0; cont
+          break/T  vm_fault $task7.0
+          cond #2  ($work0) set $work1 ($work1+1); cont
+          break/Tu xxx_end $task7.0
+          cond #3  ($work0) print $work1 " faults\n"; set $work0 0
+          cont
+
+     will print page fault counts from `xxx_start' to `xxx_end' in
+     `task7'.
+
+`step[/p] [,COUNT]'
+     Single step COUNT times.  If `p' option is specified, print each
+     instruction at each step.  Otherwise, only print the last
+     instruction.
+
+     Warning: depending on machine type, it may not be possible to
+     single-step through some low-level code paths or user space code.
+     On machines with software-emulated single-stepping (e.g., pmax),
+     stepping through code executed by interrupt handlers will probably
+     do the wrong thing.
+
+`continue[/c]'
+     Continue execution until a breakpoint or watchpoint.  If `/c',
+     count instructions while executing.  Some machines (e.g., pmax)
+     also count loads and stores.
+
+     Warning: when counting, the debugger is really silently
+     single-stepping.  This means that single-stepping on low-level
+     code may cause strange behavior.
+
+`until'
+     Stop at the next call or return instruction.
+
+`next[/p]'
+     Stop at the matching return instruction.  If `p' option is
+     specified, print the call nesting depth and the cumulative
+     instruction count at each call or return.  Otherwise, only print
+     when the matching return is hit.
+
+`match[/p]'
+     A synonym for `next'.
+
+`trace[/tu] [ FRAME_ADDR|THREAD ][,COUNT]'
+     Stack trace.  `u' option traces user space; if omitted, only traces
+     kernel space.  If `t' option is specified, it shows the stack trace
+     of the specified thread or a default target thread.  Otherwise, it
+     shows the stack trace of the current thread from the frame address
+     specified by a parameter or from the current frame.  COUNT is the
+     number of frames to be traced.  If the COUNT is omitted, all
+     frames are printed.
+
+     Warning: If the target thread's stack is not in the main memory at
+     that time, the stack trace will fail.  User space stack trace is
+     valid only if the machine dependent code supports it.
+
+`search[/bhl] ADDR VALUE [MASK] [,COUNT]'
+     Search memory for a value.  This command might fail in interesting
+     ways if it doesn't find the searched-for value.  This is because
+     `ddb' doesn't always recover from touching bad memory.  The
+     optional count argument limits the search.
+
+`macro NAME COMMANDS'
+     Define a debugger macro as NAME.  COMMANDS is a list of commands
+     to be associated with the macro.  In the expressions of the
+     command list, a variable `$argxx' can be used to get a parameter
+     passed to the macro.  When a macro is called, each argument is
+     evaluated as an expression, and the value is assigned to each
+     parameter, `$arg1', `$arg2', ... respectively.  10 `$arg'
+     variables are reserved to each level of macros, and they can be
+     used as local variables.  The nesting of macro can be allowed up
+     to 5 levels.  For example,
+
+          macro xinit set $work0 $arg1
+          macro xlist examine/m $work0,4; set $work0 *($work0)
+          xinit *(xxx_list)
+          xlist
+          ....
+
+     will print the contents of a list starting from `xxx_list' by each
+     `xlist' command.
+
+`dmacro NAME'
+     Delete the macro named NAME.
+
+`show all threads[/ul]'
+     Display all tasks and threads information.  This version of `ddb'
+     prints more information than previous one.  It shows UNIX process
+     information like `ps' for each task.  The UNIX process information
+     may not be shown if it is not supported in the machine, or the
+     bottom of the stack of the target task is not in the main memory at
+     that time.  It also shows task and thread identification numbers.
+     These numbers can be used to specify a task or a thread
+     symbolically in various commands.  The numbers are valid only in
+     the same debugger session.  If the execution is resumed again, the
+     numbers may change.  The current thread can be distinguished from
+     others by a `#' after the thread id instead of `:'.  Without `l'
+     option, it only shows thread id, thread structure address and the
+     status for each thread.  The status consists of 5 letters, R(run),
+     W(wait), S(sus­ pended), O(swapped out) and N(interruptible), and
+     if corresponding status bit is off, `.'  is printed instead.  If
+     `l' option is specified, more detail information is printed for
+     each thread.
+
+`show task [ ADDR ]'
+     Display the information of a task specified by ADDR.  If ADDR is
+     omitted, current task information is displayed.
+
+`show thread [ ADDR ]'
+     Display the information of a thread specified by ADDR.  If ADDR is
+     omitted, current thread information is displayed.
+
+`show registers[/tu [ THREAD ]]'
+     Display the register set.  Target thread can be specified with `t'
+     option and THREAD parameter.  If `u' option is specified, it
+     displays user registers instead of kernel or currently saved one.
+
+     Warning: The support of `t' and `u' option depends on the machine.
+     If not supported, incorrect information will be displayed.
+
+`show map ADDR'
+     Prints the `vm_map' at ADDR.
+
+`show object ADDR'
+     Prints the `vm_object' at ADDR.
+
+`show page ADDR'
+     Prints the `vm_page' structure at ADDR.
+
+`show port ADDR'
+     Prints the `ipc_port' structure at ADDR.
+
+`show ipc_port[/t [ THREAD ]]'
+     Prints all `ipc_port' structure's addresses the target thread has.
+     The target thread is a current thread or that specified by a
+     parameter.
+
+`show macro [ NAME ]'
+     Show the definitions of macros.  If NAME is specified, only the
+     definition of it is displayed.  Otherwise, definitions of all
+     macros are displayed.
+
+`show watches'
+     Displays all watchpoints.
+
+`watch[/T] ADDR,SIZE [ TASK ]'
+     Set a watchpoint for a region.  Execution stops when an attempt to
+     modify the region occurs.  The SIZE argument defaults to 4.
+     Without `T' option, ADDR is assumed to be a kernel address.  If
+     you want to set a watch point in user space, specify `T' and TASK
+     parameter where the address belongs to.  If the TASK parameter is
+     omitted, a task of the default target thread or a current task is
+     assumed.  If you specify a wrong space address, the request is
+     rejected with an error message.
+
+     Warning: Attempts to watch wired kernel memory may cause
+     unrecoverable error in some systems such as i386.  Watchpoints on
+     user addresses work best.
+
+
+File: mach.info,  Node: Variables,  Next: Expressions,  Prev: Commands,  Up: Kernel Debugger
+
+11.3 Variables
+==============
+
+The debugger accesses registers and variables as $NAME.  Register names
+are as in the `show registers' command.  Some variables are suffixed
+with numbers, and may have some modifier following a colon immediately
+after the variable name.  For example, register variables can have `u'
+and `t' modifier to indicate user register and that of a default target
+thread instead of that of the current thread (e.g. `$eax:tu').
+
+   Built-in variables currently supported are:
+
+`taskXX[.YY]'
+     Task or thread structure address.  XX and YY are task and thread
+     identification numbers printed by a `show all threads' command
+     respectively.  This variable is read only.
+
+`thread'
+     The default target thread.  The value is used when `t' option is
+     specified without explicit thread structure address parameter in
+     command lines or expression evaluation.
+
+`radix'
+     Input and output radix
+
+`maxoff'
+     Addresses are printed as SYMBOL+OFFSET unless offset is greater
+     than maxoff.
+
+`maxwidth'
+     The width of the displayed line.
+
+`lines'
+     The number of lines.  It is used by `more' feature.
+
+`tabstops'
+     Tab stop width.
+
+`argXX'
+     Parameters passed to a macro.  XX can be 1 to 10.
+
+`workXX'
+     Work variable.  XX can be 0 to 31.
+
+
+File: mach.info,  Node: Expressions,  Prev: Variables,  Up: Kernel Debugger
+
+11.4 Expressions
+================
+
+Almost all expression operators in C are supported except `~', `^', and
+unary `&'.  Special rules in `ddb' are:
+
+`IDENTIFIER'
+     name of a symbol.  It is translated to the address(or value) of it.
+     `.'  and `:' can be used in the identifier.  If supported by an
+     object format dependent routine, [FILE_NAME:]FUNC[:LINE_NUMBER]
+     [FILE_NAME:]VARIABLE, and FILE_NAME[:LINE_NUMBER] can be accepted
+     as a symbol.  The symbol may be prefixed with
+     `SYMBOL_TABLE_NAME::' like `emulator::mach_msg_trap' to specify
+     other than kernel symbols.
+
+`NUMBER'
+     radix is determined by the first two letters:
+    `0x'
+          hex
+
+    `0o'
+          octal
+
+    `0t'
+          decimal
+
+     otherwise, follow current radix.
+
+`.'
+     dot
+
+`+'
+     next
+
+`..'
+     address of the start of the last line examined.  Unlike dot or
+     next, this is only changed by `examine' or `write' command.
+
+`´'
+     last address explicitly specified.
+
+`$VARIABLE'
+     register name or variable.  It is translated to the value of it.
+     It may be followed by a `:' and modifiers as described above.
+
+`a'
+     multiple of right hand side.
+
+`*EXPR'
+     indirection.  It may be followed by a `:' and modifiers as
+     described above.
+
+
+File: mach.info,  Node: Copying,  Next: Documentation License,  Prev: Kernel Debugger,  Up: Top
+
+Appendix A GNU GENERAL PUBLIC LICENSE
+*************************************
+
+                         Version 2, June 1991
+
+     Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+     59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
+
+     Everyone is permitted to copy and distribute verbatim copies
+     of this license document, but changing it is not allowed.
+
+A.0.1 Preamble
+--------------
+
+The licenses for most software are designed to take away your freedom
+to share and change it.  By contrast, the GNU General Public License is
+intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.)  You can apply it to
+your programs, too.
+
+   When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it in
+new free programs; and that you know you can do these things.
+
+   To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+   For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+   We protect your rights with two steps: (1) copyright the software,
+and (2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+   Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+   Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+   The precise terms and conditions for copying, distribution and
+modification follow.
+
+    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+  1. This License applies to any program or other work which contains a
+     notice placed by the copyright holder saying it may be distributed
+     under the terms of this General Public License.  The "Program",
+     below, refers to any such program or work, and a "work based on
+     the Program" means either the Program or any derivative work under
+     copyright law: that is to say, a work containing the Program or a
+     portion of it, either verbatim or with modifications and/or
+     translated into another language.  (Hereinafter, translation is
+     included without limitation in the term "modification".)  Each
+     licensee is addressed as "you".
+
+     Activities other than copying, distribution and modification are
+     not covered by this License; they are outside its scope.  The act
+     of running the Program is not restricted, and the output from the
+     Program is covered only if its contents constitute a work based on
+     the Program (independent of having been made by running the
+     Program).  Whether that is true depends on what the Program does.
+
+  2. You may copy and distribute verbatim copies of the Program's
+     source code as you receive it, in any medium, provided that you
+     conspicuously and appropriately publish on each copy an appropriate
+     copyright notice and disclaimer of warranty; keep intact all the
+     notices that refer to this License and to the absence of any
+     warranty; and give any other recipients of the Program a copy of
+     this License along with the Program.
+
+     You may charge a fee for the physical act of transferring a copy,
+     and you may at your option offer warranty protection in exchange
+     for a fee.
+
+  3. You may modify your copy or copies of the Program or any portion
+     of it, thus forming a work based on the Program, and copy and
+     distribute such modifications or work under the terms of Section 1
+     above, provided that you also meet all of these conditions:
+
+       a. You must cause the modified files to carry prominent notices
+          stating that you changed the files and the date of any change.
+
+       b. You must cause any work that you distribute or publish, that
+          in whole or in part contains or is derived from the Program
+          or any part thereof, to be licensed as a whole at no charge
+          to all third parties under the terms of this License.
+
+       c. If the modified program normally reads commands interactively
+          when run, you must cause it, when started running for such
+          interactive use in the most ordinary way, to print or display
+          an announcement including an appropriate copyright notice and
+          a notice that there is no warranty (or else, saying that you
+          provide a warranty) and that users may redistribute the
+          program under these conditions, and telling the user how to
+          view a copy of this License.  (Exception: if the Program
+          itself is interactive but does not normally print such an
+          announcement, your work based on the Program is not required
+          to print an announcement.)
+
+     These requirements apply to the modified work as a whole.  If
+     identifiable sections of that work are not derived from the
+     Program, and can be reasonably considered independent and separate
+     works in themselves, then this License, and its terms, do not
+     apply to those sections when you distribute them as separate
+     works.  But when you distribute the same sections as part of a
+     whole which is a work based on the Program, the distribution of
+     the whole must be on the terms of this License, whose permissions
+     for other licensees extend to the entire whole, and thus to each
+     and every part regardless of who wrote it.
+
+     Thus, it is not the intent of this section to claim rights or
+     contest your rights to work written entirely by you; rather, the
+     intent is to exercise the right to control the distribution of
+     derivative or collective works based on the Program.
+
+     In addition, mere aggregation of another work not based on the
+     Program with the Program (or with a work based on the Program) on
+     a volume of a storage or distribution medium does not bring the
+     other work under the scope of this License.
+
+  4. You may copy and distribute the Program (or a work based on it,
+     under Section 2) in object code or executable form under the terms
+     of Sections 1 and 2 above provided that you also do one of the
+     following:
+
+       a. Accompany it with the complete corresponding machine-readable
+          source code, which must be distributed under the terms of
+          Sections 1 and 2 above on a medium customarily used for
+          software interchange; or,
+
+       b. Accompany it with a written offer, valid for at least three
+          years, to give any third party, for a charge no more than your
+          cost of physically performing source distribution, a complete
+          machine-readable copy of the corresponding source code, to be
+          distributed under the terms of Sections 1 and 2 above on a
+          medium customarily used for software interchange; or,
+
+       c. Accompany it with the information you received as to the offer
+          to distribute corresponding source code.  (This alternative is
+          allowed only for noncommercial distribution and only if you
+          received the program in object code or executable form with
+          such an offer, in accord with Subsection b above.)
+
+     The source code for a work means the preferred form of the work for
+     making modifications to it.  For an executable work, complete
+     source code means all the source code for all modules it contains,
+     plus any associated interface definition files, plus the scripts
+     used to control compilation and installation of the executable.
+     However, as a special exception, the source code distributed need
+     not include anything that is normally distributed (in either
+     source or binary form) with the major components (compiler,
+     kernel, and so on) of the operating system on which the executable
+     runs, unless that component itself accompanies the executable.
+
+     If distribution of executable or object code is made by offering
+     access to copy from a designated place, then offering equivalent
+     access to copy the source code from the same place counts as
+     distribution of the source code, even though third parties are not
+     compelled to copy the source along with the object code.
+
+  5. You may not copy, modify, sublicense, or distribute the Program
+     except as expressly provided under this License.  Any attempt
+     otherwise to copy, modify, sublicense or distribute the Program is
+     void, and will automatically terminate your rights under this
+     License.  However, parties who have received copies, or rights,
+     from you under this License will not have their licenses
+     terminated so long as such parties remain in full compliance.
+
+  6. You are not required to accept this License, since you have not
+     signed it.  However, nothing else grants you permission to modify
+     or distribute the Program or its derivative works.  These actions
+     are prohibited by law if you do not accept this License.
+     Therefore, by modifying or distributing the Program (or any work
+     based on the Program), you indicate your acceptance of this
+     License to do so, and all its terms and conditions for copying,
+     distributing or modifying the Program or works based on it.
+
+  7. Each time you redistribute the Program (or any work based on the
+     Program), the recipient automatically receives a license from the
+     original licensor to copy, distribute or modify the Program
+     subject to these terms and conditions.  You may not impose any
+     further restrictions on the recipients' exercise of the rights
+     granted herein.  You are not responsible for enforcing compliance
+     by third parties to this License.
+
+  8. If, as a consequence of a court judgment or allegation of patent
+     infringement or for any other reason (not limited to patent
+     issues), conditions are imposed on you (whether by court order,
+     agreement or otherwise) that contradict the conditions of this
+     License, they do not excuse you from the conditions of this
+     License.  If you cannot distribute so as to satisfy simultaneously
+     your obligations under this License and any other pertinent
+     obligations, then as a consequence you may not distribute the
+     Program at all.  For example, if a patent license would not permit
+     royalty-free redistribution of the Program by all those who
+     receive copies directly or indirectly through you, then the only
+     way you could satisfy both it and this License would be to refrain
+     entirely from distribution of the Program.
+
+     If any portion of this section is held invalid or unenforceable
+     under any particular circumstance, the balance of the section is
+     intended to apply and the section as a whole is intended to apply
+     in other circumstances.
+
+     It is not the purpose of this section to induce you to infringe any
+     patents or other property right claims or to contest validity of
+     any such claims; this section has the sole purpose of protecting
+     the integrity of the free software distribution system, which is
+     implemented by public license practices.  Many people have made
+     generous contributions to the wide range of software distributed
+     through that system in reliance on consistent application of that
+     system; it is up to the author/donor to decide if he or she is
+     willing to distribute software through any other system and a
+     licensee cannot impose that choice.
+
+     This section is intended to make thoroughly clear what is believed
+     to be a consequence of the rest of this License.
+
+  9. If the distribution and/or use of the Program is restricted in
+     certain countries either by patents or by copyrighted interfaces,
+     the original copyright holder who places the Program under this
+     License may add an explicit geographical distribution limitation
+     excluding those countries, so that distribution is permitted only
+     in or among countries not thus excluded.  In such case, this
+     License incorporates the limitation as if written in the body of
+     this License.
+
+ 10. The Free Software Foundation may publish revised and/or new
+     versions of the General Public License from time to time.  Such
+     new versions will be similar in spirit to the present version, but
+     may differ in detail to address new problems or concerns.
+
+     Each version is given a distinguishing version number.  If the
+     Program specifies a version number of this License which applies
+     to it and "any later version", you have the option of following
+     the terms and conditions either of that version or of any later
+     version published by the Free Software Foundation.  If the Program
+     does not specify a version number of this License, you may choose
+     any version ever published by the Free Software Foundation.
+
+ 11. If you wish to incorporate parts of the Program into other free
+     programs whose distribution conditions are different, write to the
+     author to ask for permission.  For software which is copyrighted
+     by the Free Software Foundation, write to the Free Software
+     Foundation; we sometimes make exceptions for this.  Our decision
+     will be guided by the two goals of preserving the free status of
+     all derivatives of our free software and of promoting the sharing
+     and reuse of software generally.
+
+                                NO WARRANTY
+ 12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
+     WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
+     LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+     HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
+     WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
+     NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+     FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE
+     QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+     PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
+     SERVICING, REPAIR OR CORRECTION.
+
+ 13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
+     MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
+     LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
+     INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
+     INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+     DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
+     OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
+     OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
+     ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+                      END OF TERMS AND CONDITIONS
+How to Apply These Terms to Your New Programs
+=============================================
+
+If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these
+terms.
+
+   To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+     ONE LINE TO GIVE THE PROGRAM'S NAME AND AN IDEA OF WHAT IT DOES.
+     Copyright (C) 19YY  NAME OF AUTHOR
+
+     This program is free software; you can redistribute it and/or
+     modify it under the terms of the GNU General Public License
+     as published by the Free Software Foundation; either version 2
+     of the License, or (at your option) any later version.
+
+     This program is distributed in the hope that it will be useful,
+     but WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+     GNU General Public License for more details.
+
+     You should have received a copy of the GNU General Public License along
+     with this program; if not, write to the Free Software Foundation, Inc.,
+     59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
+
+   Also add information on how to contact you by electronic and paper
+mail.
+
+   If the program is interactive, make it output a short notice like
+this when it starts in an interactive mode:
+
+     Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
+     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
+     type `show w'.  This is free software, and you are welcome
+     to redistribute it under certain conditions; type `show c'
+     for details.
+
+   The hypothetical commands `show w' and `show c' should show the
+appropriate parts of the General Public License.  Of course, the
+commands you use may be called something other than `show w' and `show
+c'; they could even be mouse-clicks or menu items--whatever suits your
+program.
+
+   You should also get your employer (if you work as a programmer) or
+your school, if any, to sign a "copyright disclaimer" for the program,
+if necessary.  Here is a sample; alter the names:
+
+     Yoyodyne, Inc., hereby disclaims all copyright
+     interest in the program `Gnomovision'
+     (which makes passes at compilers) written
+     by James Hacker.
+
+     SIGNATURE OF TY COON, 1 April 1989
+     Ty Coon, President of Vice
+
+   This General Public License does not permit incorporating your
+program into proprietary programs.  If your program is a subroutine
+library, you may consider it more useful to permit linking proprietary
+applications with the library.  If this is what you want to do, use the
+GNU Library General Public License instead of this License.
+
+
+File: mach.info,  Node: Documentation License,  Next: Concept Index,  Prev: Copying,  Up: Top
+
+Appendix B Documentation License
+********************************
+
+This manual is copyrighted and licensed under the GNU Free Documentation
+license.
+
+   Parts of this manual are derived from the Mach manual packages
+originally provided by Carnegie Mellon University.
+
+* Menu:
+
+* Free Documentation License::    The GNU Free Documentation License.
+* CMU License::                   The CMU license applies to the original Mach
+                                  kernel and its documentation.
+
+
+File: mach.info,  Node: Free Documentation License,  Next: CMU License,  Up: Documentation License
+
+B.1 GNU Free Documentation License
+==================================
+
+                        Version 1.1, March 2000
+
+     Copyright (C) 2000 Free Software Foundation, Inc.
+     59 Temple Place, Suite 330, Boston, MA  02111-1307, USA
+
+     Everyone is permitted to copy and distribute verbatim copies
+     of this license document, but changing it is not allowed.
+
+  0. PREAMBLE
+
+     The purpose of this License is to make a manual, textbook, or other
+     written document "free" in the sense of freedom: to assure everyone
+     the effective freedom to copy and redistribute it, with or without
+     modifying it, either commercially or noncommercially.  Secondarily,
+     this License preserves for the author and publisher a way to get
+     credit for their work, while not being considered responsible for
+     modifications made by others.
+
+     This License is a kind of "copyleft", which means that derivative
+     works of the document must themselves be free in the same sense.
+     It complements the GNU General Public License, which is a copyleft
+     license designed for free software.
+
+     We have designed this License in order to use it for manuals for
+     free software, because free software needs free documentation: a
+     free program should come with manuals providing the same freedoms
+     that the software does.  But this License is not limited to
+     software manuals; it can be used for any textual work, regardless
+     of subject matter or whether it is published as a printed book.
+     We recommend this License principally for works whose purpose is
+     instruction or reference.
+
+  1. APPLICABILITY AND DEFINITIONS
+
+     This License applies to any manual or other work that contains a
+     notice placed by the copyright holder saying it can be distributed
+     under the terms of this License.  The "Document", below, refers to
+     any such manual or work.  Any member of the public is a licensee,
+     and is addressed as "you".
+
+     A "Modified Version" of the Document means any work containing the
+     Document or a portion of it, either copied verbatim, or with
+     modifications and/or translated into another language.
+
+     A "Secondary Section" is a named appendix or a front-matter
+     section of the Document that deals exclusively with the
+     relationship of the publishers or authors of the Document to the
+     Document's overall subject (or to related matters) and contains
+     nothing that could fall directly within that overall subject.
+     (For example, if the Document is in part a textbook of
+     mathematics, a Secondary Section may not explain any mathematics.)
+     The relationship could be a matter of historical connection with
+     the subject or with related matters, or of legal, commercial,
+     philosophical, ethical or political position regarding them.
+
+     The "Invariant Sections" are certain Secondary Sections whose
+     titles are designated, as being those of Invariant Sections, in
+     the notice that says that the Document is released under this
+     License.
+
+     The "Cover Texts" are certain short passages of text that are
+     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
+     that says that the Document is released under this License.
+
+     A "Transparent" copy of the Document means a machine-readable copy,
+     represented in a format whose specification is available to the
+     general public, whose contents can be viewed and edited directly
+     and straightforwardly with generic text editors or (for images
+     composed of pixels) generic paint programs or (for drawings) some
+     widely available drawing editor, and that is suitable for input to
+     text formatters or for automatic translation to a variety of
+     formats suitable for input to text formatters.  A copy made in an
+     otherwise Transparent file format whose markup has been designed
+     to thwart or discourage subsequent modification by readers is not
+     Transparent.  A copy that is not "Transparent" is called "Opaque".
+
+     Examples of suitable formats for Transparent copies include plain
+     ASCII without markup, Texinfo input format, LaTeX input format,
+     SGML or XML using a publicly available DTD, and
+     standard-conforming simple HTML designed for human modification.
+     Opaque formats include PostScript, PDF, proprietary formats that
+     can be read and edited only by proprietary word processors, SGML
+     or XML for which the DTD and/or processing tools are not generally
+     available, and the machine-generated HTML produced by some word
+     processors for output purposes only.
+
+     The "Title Page" means, for a printed book, the title page itself,
+     plus such following pages as are needed to hold, legibly, the
+     material this License requires to appear in the title page.  For
+     works in formats which do not have any title page as such, "Title
+     Page" means the text near the most prominent appearance of the
+     work's title, preceding the beginning of the body of the text.
+
+  2. VERBATIM COPYING
+
+     You may copy and distribute the Document in any medium, either
+     commercially or noncommercially, provided that this License, the
+     copyright notices, and the license notice saying this License
+     applies to the Document are reproduced in all copies, and that you
+     add no other conditions whatsoever to those of this License.  You
+     may not use technical measures to obstruct or control the reading
+     or further copying of the copies you make or distribute.  However,
+     you may accept compensation in exchange for copies.  If you
+     distribute a large enough number of copies you must also follow
+     the conditions in section 3.
+
+     You may also lend copies, under the same conditions stated above,
+     and you may publicly display copies.
+
+  3. COPYING IN QUANTITY
+
+     If you publish printed copies of the Document numbering more than
+     100, and the Document's license notice requires Cover Texts, you
+     must enclose the copies in covers that carry, clearly and legibly,
+     all these Cover Texts: Front-Cover Texts on the front cover, and
+     Back-Cover Texts on the back cover.  Both covers must also clearly
+     and legibly identify you as the publisher of these copies.  The
+     front cover must present the full title with all words of the
+     title equally prominent and visible.  You may add other material
+     on the covers in addition.  Copying with changes limited to the
+     covers, as long as they preserve the title of the Document and
+     satisfy these conditions, can be treated as verbatim copying in
+     other respects.
+
+     If the required texts for either cover are too voluminous to fit
+     legibly, you should put the first ones listed (as many as fit
+     reasonably) on the actual cover, and continue the rest onto
+     adjacent pages.
+
+     If you publish or distribute Opaque copies of the Document
+     numbering more than 100, you must either include a
+     machine-readable Transparent copy along with each Opaque copy, or
+     state in or with each Opaque copy a publicly-accessible
+     computer-network location containing a complete Transparent copy
+     of the Document, free of added material, which the general
+     network-using public has access to download anonymously at no
+     charge using public-standard network protocols.  If you use the
+     latter option, you must take reasonably prudent steps, when you
+     begin distribution of Opaque copies in quantity, to ensure that
+     this Transparent copy will remain thus accessible at the stated
+     location until at least one year after the last time you
+     distribute an Opaque copy (directly or through your agents or
+     retailers) of that edition to the public.
+
+     It is requested, but not required, that you contact the authors of
+     the Document well before redistributing any large number of
+     copies, to give them a chance to provide you with an updated
+     version of the Document.
+
+  4. MODIFICATIONS
+
+     You may copy and distribute a Modified Version of the Document
+     under the conditions of sections 2 and 3 above, provided that you
+     release the Modified Version under precisely this License, with
+     the Modified Version filling the role of the Document, thus
+     licensing distribution and modification of the Modified Version to
+     whoever possesses a copy of it.  In addition, you must do these
+     things in the Modified Version:
+
+       A. Use in the Title Page (and on the covers, if any) a title
+          distinct from that of the Document, and from those of
+          previous versions (which should, if there were any, be listed
+          in the History section of the Document).  You may use the
+          same title as a previous version if the original publisher of
+          that version gives permission.
+
+       B. List on the Title Page, as authors, one or more persons or
+          entities responsible for authorship of the modifications in
+          the Modified Version, together with at least five of the
+          principal authors of the Document (all of its principal
+          authors, if it has less than five).
+
+       C. State on the Title page the name of the publisher of the
+          Modified Version, as the publisher.
+
+       D. Preserve all the copyright notices of the Document.
+
+       E. Add an appropriate copyright notice for your modifications
+          adjacent to the other copyright notices.
+
+       F. Include, immediately after the copyright notices, a license
+          notice giving the public permission to use the Modified
+          Version under the terms of this License, in the form shown in
+          the Addendum below.
+
+       G. Preserve in that license notice the full lists of Invariant
+          Sections and required Cover Texts given in the Document's
+          license notice.
+
+       H. Include an unaltered copy of this License.
+
+       I. Preserve the section entitled "History", and its title, and
+          add to it an item stating at least the title, year, new
+          authors, and publisher of the Modified Version as given on
+          the Title Page.  If there is no section entitled "History" in
+          the Document, create one stating the title, year, authors,
+          and publisher of the Document as given on its Title Page,
+          then add an item describing the Modified Version as stated in
+          the previous sentence.
+
+       J. Preserve the network location, if any, given in the Document
+          for public access to a Transparent copy of the Document, and
+          likewise the network locations given in the Document for
+          previous versions it was based on.  These may be placed in
+          the "History" section.  You may omit a network location for a
+          work that was published at least four years before the
+          Document itself, or if the original publisher of the version
+          it refers to gives permission.
+
+       K. In any section entitled "Acknowledgments" or "Dedications",
+          preserve the section's title, and preserve in the section all
+          the substance and tone of each of the contributor
+          acknowledgments and/or dedications given therein.
+
+       L. Preserve all the Invariant Sections of the Document,
+          unaltered in their text and in their titles.  Section numbers
+          or the equivalent are not considered part of the section
+          titles.
+
+       M. Delete any section entitled "Endorsements".  Such a section
+          may not be included in the Modified Version.
+
+       N. Do not retitle any existing section as "Endorsements" or to
+          conflict in title with any Invariant Section.
+
+     If the Modified Version includes new front-matter sections or
+     appendices that qualify as Secondary Sections and contain no
+     material copied from the Document, you may at your option
+     designate some or all of these sections as invariant.  To do this,
+     add their titles to the list of Invariant Sections in the Modified
+     Version's license notice.  These titles must be distinct from any
+     other section titles.
+
+     You may add a section entitled "Endorsements", provided it contains
+     nothing but endorsements of your Modified Version by various
+     parties--for example, statements of peer review or that the text
+     has been approved by an organization as the authoritative
+     definition of a standard.
+
+     You may add a passage of up to five words as a Front-Cover Text,
+     and a passage of up to 25 words as a Back-Cover Text, to the end
+     of the list of Cover Texts in the Modified Version.  Only one
+     passage of Front-Cover Text and one of Back-Cover Text may be
+     added by (or through arrangements made by) any one entity.  If the
+     Document already includes a cover text for the same cover,
+     previously added by you or by arrangement made by the same entity
+     you are acting on behalf of, you may not add another; but you may
+     replace the old one, on explicit permission from the previous
+     publisher that added the old one.
+
+     The author(s) and publisher(s) of the Document do not by this
+     License give permission to use their names for publicity for or to
+     assert or imply endorsement of any Modified Version.
+
+  5. COMBINING DOCUMENTS
+
+     You may combine the Document with other documents released under
+     this License, under the terms defined in section 4 above for
+     modified versions, provided that you include in the combination
+     all of the Invariant Sections of all of the original documents,
+     unmodified, and list them all as Invariant Sections of your
+     combined work in its license notice.
+
+     The combined work need only contain one copy of this License, and
+     multiple identical Invariant Sections may be replaced with a single
+     copy.  If there are multiple Invariant Sections with the same name
+     but different contents, make the title of each such section unique
+     by adding at the end of it, in parentheses, the name of the
+     original author or publisher of that section if known, or else a
+     unique number.  Make the same adjustment to the section titles in
+     the list of Invariant Sections in the license notice of the
+     combined work.
+
+     In the combination, you must combine any sections entitled
+     "History" in the various original documents, forming one section
+     entitled "History"; likewise combine any sections entitled
+     "Acknowledgments", and any sections entitled "Dedications".  You
+     must delete all sections entitled "Endorsements."
+
+  6. COLLECTIONS OF DOCUMENTS
+
+     You may make a collection consisting of the Document and other
+     documents released under this License, and replace the individual
+     copies of this License in the various documents with a single copy
+     that is included in the collection, provided that you follow the
+     rules of this License for verbatim copying of each of the
+     documents in all other respects.
+
+     You may extract a single document from such a collection, and
+     distribute it individually under this License, provided you insert
+     a copy of this License into the extracted document, and follow
+     this License in all other respects regarding verbatim copying of
+     that document.
+
+  7. AGGREGATION WITH INDEPENDENT WORKS
+
+     A compilation of the Document or its derivatives with other
+     separate and independent documents or works, in or on a volume of
+     a storage or distribution medium, does not as a whole count as a
+     Modified Version of the Document, provided no compilation
+     copyright is claimed for the compilation.  Such a compilation is
+     called an "aggregate", and this License does not apply to the
+     other self-contained works thus compiled with the Document, on
+     account of their being thus compiled, if they are not themselves
+     derivative works of the Document.
+
+     If the Cover Text requirement of section 3 is applicable to these
+     copies of the Document, then if the Document is less than one
+     quarter of the entire aggregate, the Document's Cover Texts may be
+     placed on covers that surround only the Document within the
+     aggregate.  Otherwise they must appear on covers around the whole
+     aggregate.
+
+  8. TRANSLATION
+
+     Translation is considered a kind of modification, so you may
+     distribute translations of the Document under the terms of section
+     4.  Replacing Invariant Sections with translations requires special
+     permission from their copyright holders, but you may include
+     translations of some or all Invariant Sections in addition to the
+     original versions of these Invariant Sections.  You may include a
+     translation of this License provided that you also include the
+     original English version of this License.  In case of a
+     disagreement between the translation and the original English
+     version of this License, the original English version will prevail.
+
+  9. TERMINATION
+
+     You may not copy, modify, sublicense, or distribute the Document
+     except as expressly provided for under this License.  Any other
+     attempt to copy, modify, sublicense or distribute the Document is
+     void, and will automatically terminate your rights under this
+     License.  However, parties who have received copies, or rights,
+     from you under this License will not have their licenses
+     terminated so long as such parties remain in full compliance.
+
+ 10. FUTURE REVISIONS OF THIS LICENSE
+
+     The Free Software Foundation may publish new, revised versions of
+     the GNU Free Documentation License from time to time.  Such new
+     versions will be similar in spirit to the present version, but may
+     differ in detail to address new problems or concerns.  See
+     `http://www.gnu.org/copyleft/'.
+
+     Each version of the License is given a distinguishing version
+     number.  If the Document specifies that a particular numbered
+     version of this License "or any later version" applies to it, you
+     have the option of following the terms and conditions either of
+     that specified version or of any later version that has been
+     published (not as a draft) by the Free Software Foundation.  If
+     the Document does not specify a version number of this License,
+     you may choose any version ever published (not as a draft) by the
+     Free Software Foundation.
+
+B.1.0.1 ADDENDUM: How to use this License for your documents
+............................................................
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and license
+notices just after the title page:
+
+       Copyright (C)  YEAR  YOUR NAME.
+       Permission is granted to copy, distribute and/or modify this document
+       under the terms of the GNU Free Documentation License, Version 1.1
+       or any later version published by the Free Software Foundation;
+       with the Invariant Sections being LIST THEIR TITLES, with the
+       Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+       A copy of the license is included in the section entitled ``GNU
+       Free Documentation License''.
+
+   If you have no Invariant Sections, write "with no Invariant Sections"
+instead of saying which ones are invariant.  If you have no Front-Cover
+Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
+LIST"; likewise for Back-Cover Texts.
+
+   If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License, to
+permit their use in free software.
+
+
+File: mach.info,  Node: CMU License,  Prev: Free Documentation License,  Up: Documentation License
+
+B.2 CMU License
+===============
+
+          Mach Operating System
+          Copyright (C) 1991,1990,1989 Carnegie Mellon University
+          All Rights Reserved.
+
+     Permission to use, copy, modify and distribute this software and
+     its documentation is hereby granted, provided that both the
+     copyright notice and this permission notice appear in all copies
+     of the software, derivative works or modified versions, and any
+     portions thereof, and that both notices appear in supporting
+     documentation.
+
+     CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
+     CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
+     ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
+
+     Carnegie Mellon requests users of this software to return to
+
+           Software Distribution Coordinator
+           School of Computer Science
+           Carnegie Mellon University
+           Pittsburgh PA 15213-3890
+
+     or <Software.Distribution@CS.CMU.EDU> any improvements or
+     extensions that they make and grant Carnegie Mellon the rights to
+     redistribute these changes.
+
+
+File: mach.info,  Node: Concept Index,  Next: Function and Data Index,  Prev: Documentation License,  Up: Top
+
+Concept Index
+*************
+
+
+* Menu:
+
+* communication between tasks:           Major Concepts.       (line  6)
+* composing messages:                    Message Format.       (line  6)
+* device port:                           Device Interface.     (line 13)
+* FDL, GNU Free Documentation License:   Free Documentation License.
+                                                               (line  6)
+* format of a message:                   Message Format.       (line  6)
+* GPL, GNU General Public License:       Copying.              (line  6)
+* GRand Unified Bootloader:              Bootloader.           (line 13)
+* GRUB:                                  Bootloader.           (line 13)
+* host control port:                     Host Ports.           (line 34)
+* host interface:                        Host Interface.       (line  6)
+* host name port:                        Host Ports.           (line  6)
+* host ports:                            Host Ports.           (line  6)
+* interprocess communication (IPC):      Major Concepts.       (line  6)
+* IPC (interprocess communication):      Major Concepts.       (line  6)
+* IPC space port:                        Port Manipulation Interface.
+                                                               (line  9)
+* message composition:                   Message Format.       (line  6)
+* message format:                        Message Format.       (line  6)
+* messages:                              Major Concepts.       (line  6)
+* moving port rights:                    Exchanging Port Rights.
+                                                               (line  6)
+* port representing a device:            Device Interface.     (line 13)
+* port representing a processor:         Processor Interface.  (line  6)
+* port representing a processor set name: Processor Set Ports. (line  6)
+* port representing a task:              Task Interface.       (line  6)
+* port representing a thread:            Thread Interface.     (line  6)
+* port representing a virtual memory map: Virtual Memory Interface.
+                                                               (line  6)
+* port representing an IPC space:        Port Manipulation Interface.
+                                                               (line  9)
+* ports representing a host:             Host Ports.           (line  6)
+* ports representing a processor set:    Processor Set Ports.  (line  6)
+* processor port:                        Processor Interface.  (line  6)
+* processor set name port:               Processor Set Ports.  (line  6)
+* processor set port:                    Processor Set Ports.  (line 13)
+* processor set ports:                   Processor Set Ports.  (line  6)
+* receiving memory:                      Memory.               (line  6)
+* receiving port rights:                 Exchanging Port Rights.
+                                                               (line  6)
+* remote procedure calls (RPC):          Major Concepts.       (line  6)
+* RPC (remote procedure calls):          Major Concepts.       (line  6)
+* sending memory:                        Memory.               (line  6)
+* sending messages:                      Message Send.         (line  6)
+* sending port rights:                   Exchanging Port Rights.
+                                                               (line  6)
+* serverboot:                            Modules.              (line  6)
+* task port:                             Task Interface.       (line  6)
+* thread port:                           Thread Interface.     (line  6)
+* virtual memory map port:               Virtual Memory Interface.
+                                                               (line  6)
+
+
+File: mach.info,  Node: Function and Data Index,  Prev: Concept Index,  Up: Top
+
+Function and Data Index
+***********************
+
+
+* Menu:
+
+* catch_exception_raise:                 Exceptions.          (line   9)
+* device_close:                          Device Close.        (line   7)
+* device_get_status:                     Device Status.       (line  20)
+* device_map:                            Device Map.          (line   9)
+* device_open:                           Device Open.         (line   8)
+* device_open_request:                   Device Open.         (line  36)
+* device_read:                           Device Read.         (line   9)
+* device_read_inband:                    Device Read.         (line  27)
+* device_read_request:                   Device Read.         (line  34)
+* device_read_request_inband:            Device Read.         (line  51)
+* device_reply_server:                   Device Reply Server. (line  12)
+* device_set_filter:                     Device Filter.       (line  10)
+* device_set_status:                     Device Status.       (line   9)
+* device_t:                              Device Interface.    (line  14)
+* device_write:                          Device Write.        (line   9)
+* device_write_inband:                   Device Write.        (line  24)
+* device_write_request:                  Device Write.        (line  31)
+* device_write_request_inband:           Device Write.        (line  49)
+* ds_device_open_reply:                  Device Open.         (line  39)
+* ds_device_read_reply:                  Device Read.         (line  37)
+* ds_device_read_reply_inband:           Device Read.         (line  54)
+* ds_device_write_reply:                 Device Write.        (line  34)
+* ds_device_write_reply_inband:          Device Write.        (line  52)
+* evc_wait:                              Exceptions.          (line  18)
+* exception_raise:                       Exceptions.          (line  15)
+* host_adjust_time:                      Host Time.           (line  43)
+* host_basic_info_t:                     Host Information.    (line  75)
+* host_get_boot_info:                    Host Information.    (line 114)
+* host_get_time:                         Host Time.           (line  34)
+* host_info:                             Host Information.    (line   9)
+* host_kernel_version:                   Host Information.    (line  96)
+* host_priv_t:                           Host Ports.          (line  35)
+* host_processor_set_priv:               Processor Set Access.
+                                                              (line  25)
+* host_processor_sets:                   Processor Set Access.
+                                                              (line   9)
+* host_processors:                       Hosted Processors.   (line   9)
+* host_reboot:                           Host Reboot.         (line   8)
+* host_sched_info_t:                     Host Information.    (line  92)
+* host_set_time:                         Host Time.           (line  39)
+* host_t:                                Host Ports.          (line   7)
+* ipc_space_t:                           Port Manipulation Interface.
+                                                              (line  10)
+* mach_host_self:                        Host Ports.          (line  14)
+* mach_msg:                              Mach Message Call.   (line  13)
+* mach_msg_bits_t:                       Message Format.      (line  21)
+* mach_msg_header_t:                     Message Format.      (line  33)
+* mach_msg_id_t:                         Message Format.      (line  29)
+* mach_msg_size_t:                       Message Format.      (line  25)
+* mach_msg_timeout_t:                    Mach Message Call.   (line  61)
+* mach_msg_type_long_t:                  Message Format.      (line 248)
+* mach_msg_type_name_t:                  Message Format.      (line 128)
+* mach_msg_type_number_t:                Message Format.      (line 138)
+* MACH_MSG_TYPE_PORT_ANY:                Message Format.      (line 234)
+* MACH_MSG_TYPE_PORT_ANY_RIGHT:          Message Format.      (line 244)
+* MACH_MSG_TYPE_PORT_ANY_SEND:           Message Format.      (line 239)
+* mach_msg_type_size_t:                  Message Format.      (line 133)
+* mach_msg_type_t:                       Message Format.      (line 143)
+* MACH_MSGH_BITS:                        Message Format.      (line  96)
+* MACH_MSGH_BITS_LOCAL:                  Message Format.      (line 108)
+* MACH_MSGH_BITS_OTHER:                  Message Format.      (line 117)
+* MACH_MSGH_BITS_PORTS:                  Message Format.      (line 112)
+* MACH_MSGH_BITS_REMOTE:                 Message Format.      (line 103)
+* mach_port_allocate:                    Port Creation.       (line   8)
+* mach_port_allocate_name:               Port Creation.       (line  66)
+* mach_port_deallocate:                  Port Destruction.    (line   8)
+* mach_port_destroy:                     Port Destruction.    (line  30)
+* mach_port_extract_right:               Ports and other Tasks.
+                                                              (line  59)
+* mach_port_get_receive_status:          Receive Rights.      (line  57)
+* mach_port_get_refs:                    Port Rights.         (line   9)
+* mach_port_get_set_status:              Port Sets.           (line   9)
+* mach_port_insert_right:                Ports and other Tasks.
+                                                              (line   9)
+* mach_port_mod_refs:                    Port Rights.         (line  42)
+* mach_port_move_member:                 Port Sets.           (line  28)
+* mach_port_mscount_t:                   Receive Rights.      (line  11)
+* mach_port_msgcount_t:                  Receive Rights.      (line  15)
+* mach_port_names:                       Port Names.          (line   9)
+* mach_port_rename:                      Port Names.          (line  77)
+* mach_port_request_notification:        Request Notifications.
+                                                              (line  10)
+* mach_port_rights_t:                    Receive Rights.      (line  19)
+* mach_port_seqno_t:                     Receive Rights.      (line   7)
+* mach_port_set_mscount:                 Receive Rights.      (line  73)
+* mach_port_set_qlimit:                  Receive Rights.      (line  90)
+* mach_port_set_seqno:                   Receive Rights.      (line 108)
+* mach_port_status_t:                    Receive Rights.      (line  23)
+* mach_port_t:                           Message Format.      (line  14)
+* mach_port_type:                        Port Names.          (line  35)
+* mach_reply_port:                       Port Creation.       (line  48)
+* mach_task_self:                        Task Information.    (line   7)
+* mach_thread_self:                      Thread Information.  (line   7)
+* mapped_time_value_t:                   Host Time.           (line  51)
+* memory_object_change_attributes:       Memory Object Attributes.
+                                                              (line  30)
+* memory_object_change_completed:        Memory Object Attributes.
+                                                              (line  63)
+* memory_object_copy:                    Memory Objects and Data.
+                                                              (line 209)
+* memory_object_create:                  Default Memory Manager.
+                                                              (line  30)
+* memory_object_data_error:              Memory Objects and Data.
+                                                              (line 157)
+* memory_object_data_initialize:         Default Memory Manager.
+                                                              (line  73)
+* memory_object_data_provided:           Memory Objects and Data.
+                                                              (line 289)
+* memory_object_data_request:            Memory Objects and Data.
+                                                              (line  49)
+* memory_object_data_return:             Memory Objects and Data.
+                                                              (line  11)
+* memory_object_data_supply:             Memory Objects and Data.
+                                                              (line  84)
+* memory_object_data_unavailable:        Memory Objects and Data.
+                                                              (line 177)
+* memory_object_data_unlock:             Memory Object Locking.
+                                                              (line  85)
+* memory_object_data_write:              Memory Objects and Data.
+                                                              (line 260)
+* memory_object_default_server:          Memory Object Server.
+                                                              (line  10)
+* memory_object_destroy:                 Memory Object Termination.
+                                                              (line  37)
+* memory_object_get_attributes:          Memory Object Attributes.
+                                                              (line  10)
+* memory_object_init:                    Memory Object Creation.
+                                                              (line  11)
+* memory_object_lock_completed:          Memory Object Locking.
+                                                              (line  59)
+* memory_object_lock_request:            Memory Object Locking.
+                                                              (line  11)
+* memory_object_ready:                   Memory Object Creation.
+                                                              (line  52)
+* memory_object_server:                  Memory Object Server.
+                                                              (line   8)
+* memory_object_set_attributes:          Memory Object Attributes.
+                                                              (line  82)
+* memory_object_supply_completed:        Memory Objects and Data.
+                                                              (line 127)
+* memory_object_terminate:               Memory Object Termination.
+                                                              (line  10)
+* processor_assign:                      Processors and Sets. (line   8)
+* processor_basic_info_t:                Processor Info.      (line  67)
+* processor_control:                     Processor Control.   (line  10)
+* processor_exit:                        Processor Control.   (line   8)
+* processor_get_assignment:              Processors and Sets. (line  32)
+* processor_info:                        Processor Info.      (line   9)
+* processor_set_basic_info_t:            Processor Set Info.  (line  75)
+* processor_set_create:                  Processor Set Creation.
+                                                              (line   8)
+* processor_set_default:                 Processor Set Access.
+                                                              (line  36)
+* processor_set_destroy:                 Processor Set Destruction.
+                                                              (line   8)
+* processor_set_info:                    Processor Set Info.  (line  10)
+* processor_set_max_priority:            Processor Set Priority.
+                                                              (line   9)
+* processor_set_name_t:                  Processor Set Ports. (line   7)
+* processor_set_policy_disable:          Processor Set Policy.
+                                                              (line  11)
+* processor_set_policy_enable:           Processor Set Policy.
+                                                              (line   8)
+* processor_set_sched_info_t:            Processor Set Info.  (line  93)
+* processor_set_t:                       Processor Set Ports. (line  14)
+* processor_set_tasks:                   Tasks and Threads on Sets.
+                                                              (line   9)
+* processor_set_threads:                 Tasks and Threads on Sets.
+                                                              (line  23)
+* processor_start:                       Processor Control.   (line   7)
+* processor_t:                           Processor Interface. (line   7)
+* sampled_pc_flavor_t:                   Profiling.           (line  67)
+* sampled_pc_t:                          Profiling.           (line  52)
+* seqnos_memory_object_change_completed: Memory Object Attributes.
+                                                              (line  67)
+* seqnos_memory_object_copy:             Memory Objects and Data.
+                                                              (line 214)
+* seqnos_memory_object_create:           Default Memory Manager.
+                                                              (line  35)
+* seqnos_memory_object_data_initialize:  Default Memory Manager.
+                                                              (line  77)
+* seqnos_memory_object_data_request:     Memory Objects and Data.
+                                                              (line  53)
+* seqnos_memory_object_data_return:      Memory Objects and Data.
+                                                              (line  16)
+* seqnos_memory_object_data_unlock:      Memory Object Locking.
+                                                              (line  89)
+* seqnos_memory_object_data_write:       Memory Objects and Data.
+                                                              (line 264)
+* seqnos_memory_object_default_server:   Memory Object Server.
+                                                              (line  14)
+* seqnos_memory_object_init:             Memory Object Creation.
+                                                              (line  16)
+* seqnos_memory_object_lock_completed:   Memory Object Locking.
+                                                              (line  63)
+* seqnos_memory_object_server:           Memory Object Server.
+                                                              (line  12)
+* seqnos_memory_object_supply_completed: Memory Objects and Data.
+                                                              (line 132)
+* seqnos_memory_object_terminate:        Memory Object Termination.
+                                                              (line  14)
+* struct host_basic_info:                Host Information.    (line  48)
+* struct host_sched_info:                Host Information.    (line  78)
+* struct processor_basic_info:           Processor Info.      (line  44)
+* struct processor_set_basic_info:       Processor Set Info.  (line  51)
+* struct processor_set_sched_info:       Processor Set Info.  (line  78)
+* struct task_basic_info:                Task Information.    (line  82)
+* struct task_events_info:               Task Information.    (line 114)
+* struct task_thread_times_info:         Task Information.    (line 145)
+* struct thread_basic_info:              Thread Information.  (line  66)
+* struct thread_sched_info:              Thread Information.  (line 128)
+* swtch:                                 Hand-Off Scheduling. (line  81)
+* swtch_pri:                             Hand-Off Scheduling. (line  93)
+* task_assign:                           Tasks and Threads on Sets.
+                                                              (line  36)
+* task_assign_default:                   Tasks and Threads on Sets.
+                                                              (line  49)
+* task_basic_info_t:                     Task Information.    (line 111)
+* task_create:                           Task Creation.       (line   8)
+* task_disable_pc_sampling:              Profiling.           (line  22)
+* task_enable_pc_sampling:               Profiling.           (line   8)
+* task_events_info_t:                    Task Information.    (line 142)
+* task_get_assignment:                   Tasks and Threads on Sets.
+                                                              (line  60)
+* task_get_bootstrap_port:               Task Special Ports.  (line  42)
+* task_get_emulation_vector:             Syscall Emulation.   (line   9)
+* task_get_exception_port:               Task Special Ports.  (line  36)
+* task_get_kernel_port:                  Task Special Ports.  (line  30)
+* task_get_sampled_pcs:                  Profiling.           (line  36)
+* task_get_special_port:                 Task Special Ports.  (line   8)
+* task_info:                             Task Information.    (line  44)
+* task_priority:                         Task Execution.      (line  29)
+* task_ras_control:                      Task Execution.      (line  47)
+* task_resume:                           Task Execution.      (line  19)
+* task_set_bootstrap_port:               Task Special Ports.  (line  78)
+* task_set_emulation:                    Syscall Emulation.   (line  22)
+* task_set_emulation_vector:             Syscall Emulation.   (line  15)
+* task_set_exception_port:               Task Special Ports.  (line  72)
+* task_set_kernel_port:                  Task Special Ports.  (line  66)
+* task_set_special_port:                 Task Special Ports.  (line  48)
+* task_suspend:                          Task Execution.      (line   7)
+* task_t:                                Task Interface.      (line   7)
+* task_terminate:                        Task Termination.    (line   7)
+* task_thread_times_info_t:              Task Information.    (line 159)
+* task_threads:                          Task Information.    (line  33)
+* thread_abort:                          Thread Execution.    (line  38)
+* thread_assign:                         Tasks and Threads on Sets.
+                                                              (line  72)
+* thread_assign_default:                 Tasks and Threads on Sets.
+                                                              (line  85)
+* thread_basic_info_t:                   Thread Information.  (line 125)
+* thread_create:                         Thread Creation.     (line   8)
+* thread_depress_abort:                  Hand-Off Scheduling. (line  74)
+* thread_disable_pc_sampling:            Profiling.           (line  24)
+* thread_enable_pc_sampling:             Profiling.           (line  10)
+* thread_get_assignment:                 Tasks and Threads on Sets.
+                                                              (line  96)
+* thread_get_exception_port:             Thread Special Ports.
+                                                              (line  27)
+* thread_get_kernel_port:                Thread Special Ports.
+                                                              (line  21)
+* thread_get_sampled_pcs:                Profiling.           (line  39)
+* thread_get_special_port:               Thread Special Ports.
+                                                              (line   8)
+* thread_get_state:                      Thread Execution.    (line 102)
+* thread_info:                           Thread Information.  (line  33)
+* thread_max_priority:                   Thread Priority.     (line  38)
+* thread_policy:                         Scheduling Policy.   (line   8)
+* thread_priority:                       Thread Priority.     (line  20)
+* thread_resume:                         Thread Execution.    (line  29)
+* thread_sched_info_t:                   Thread Information.  (line 159)
+* thread_set_exception_port:             Thread Special Ports.
+                                                              (line  52)
+* thread_set_kernel_port:                Thread Special Ports.
+                                                              (line  46)
+* thread_set_special_port:               Thread Special Ports.
+                                                              (line  33)
+* thread_set_state:                      Thread Execution.    (line 126)
+* thread_suspend:                        Thread Execution.    (line   7)
+* thread_switch:                         Hand-Off Scheduling. (line   8)
+* thread_t:                              Thread Interface.    (line   7)
+* thread_terminate:                      Thread Termination.  (line   7)
+* thread_wire:                           Thread Settings.     (line   8)
+* time_value_add:                        Host Time.           (line  25)
+* time_value_add_usec:                   Host Time.           (line  21)
+* time_value_t:                          Host Time.           (line   7)
+* vm_allocate:                           Memory Allocation.   (line   8)
+* vm_copy:                               Data Transfer.       (line  53)
+* vm_deallocate:                         Memory Deallocation. (line   8)
+* vm_inherit:                            Memory Attributes.   (line  70)
+* vm_machine_attribute:                  Memory Attributes.   (line 134)
+* vm_map:                                Mapping Memory Objects.
+                                                              (line  11)
+* vm_protect:                            Memory Attributes.   (line  36)
+* vm_read:                               Data Transfer.       (line   9)
+* vm_region:                             Memory Attributes.   (line  11)
+* vm_set_default_memory_manager:         Default Memory Manager.
+                                                              (line   8)
+* vm_statistics:                         Memory Statistics.   (line  52)
+* vm_statistics_data_t:                  Memory Statistics.   (line   7)
+* vm_task_t:                             Virtual Memory Interface.
+                                                              (line   7)
+* vm_wire:                               Memory Attributes.   (line 101)
+* vm_write:                              Data Transfer.       (line  34)
+
+
diff --git a/doc/stamp-vti b/doc/stamp-vti
new file mode 100644
index 00000000..cab3d800
--- /dev/null
+++ b/doc/stamp-vti
@@ -0,0 +1,4 @@
+@set UPDATED 7 October 2006
+@set UPDATED-MONTH October 2006
+@set EDITION 1.3.99
+@set VERSION 1.3.99