summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJustus Winter <4winter@informatik.uni-hamburg.de>2014-05-26 00:02:50 +0200
committerJustus Winter <4winter@informatik.uni-hamburg.de>2014-10-10 14:50:46 +0200
commitad0681db8840484c0a18bb69f4a9072d6e405ccd (patch)
tree38641d5a32e13c09e7022e7289a997ed0f22bfe7
parentda5dea9b6f960603f0c02b42b5cc8384194faa5b (diff)
doc: restore section `Inherited Ports'
Previously, the section `Inherited Ports' was commented out. This was done, as the functionality was unused by the Hurd. The functions `mach_ports_register' and `mach_ports_lookup' were never removed, and are exposed to user space. This patch brings the documentation back and adds a remark at the top, that the section documents the original intentions for this interface. I chose bringing back the documentation over removing the functionality because I like to make use of it as a method for service discovery that is deliberately orthogonal to the way the service lookup is usually done in the Hurd. This can be used to implement robust low-level debugging facilities. * doc/mach.texi: Restore section `Inherited Ports'.
-rw-r--r--doc/mach.texi127
1 files changed, 65 insertions, 62 deletions
diff --git a/doc/mach.texi b/doc/mach.texi
index c57e607..4cde9fe 100644
--- a/doc/mach.texi
+++ b/doc/mach.texi
@@ -193,7 +193,7 @@ Port Manipulation Interface
* Receive Rights:: How to work with receive rights.
* Port Sets:: How to work with port sets.
* Request Notifications:: How to request notifications for events.
-@c * Inherited Ports:: How to work with the inherited system ports.
+* Inherited Ports:: How to work with the inherited system ports.
Virtual Memory Interface
@@ -2198,7 +2198,7 @@ the kernel.
* Receive Rights:: How to work with receive rights.
* Port Sets:: How to work with port sets.
* Request Notifications:: How to request notifications for events.
-@c * Inherited Ports:: How to work with the inherited system ports.
+* Inherited Ports:: How to work with the inherited system ports.
@end menu
@@ -2917,66 +2917,69 @@ call's server (normally the kernel), the call may return @code{mach_msg}
return codes.
@end deftypefun
-@c The inherited ports concept is not used in the Hurd,
-@c and so the _SLOT macros are not defined in GNU Mach.
-
-@c @node Inherited Ports
-@c @subsection Inherited Ports
-
-@c @deftypefun kern_return_t mach_ports_register (@w{task_t @var{target_task}, @w{port_array_t @var{init_port_set}}, @w{int @var{init_port_array_count}})
-@c @deftypefunx kern_return_t mach_ports_lookup (@w{task_t @var{target_task}, @w{port_array_t *@var{init_port_set}}, @w{int *@var{init_port_array_count}})
-@c @code{mach_ports_register} manipulates the inherited ports array,
-@c @code{mach_ports_lookup} is used to acquire specific parent ports.
-@c @var{target_task} is the task to be affected. @var{init_port_set} is an
-@c array of system ports to be registered, or returned. Although the array
-@c size is given as variable, the kernel will only accept a limited number
-@c of ports. @var{init_port_array_count} is the number of ports returned
-@c in @var{init_port_set}.
-
-@c @code{mach_ports_register} registers an array of well-known system ports
-@c with the kernel on behalf of a specific task. Currently the ports to be
-@c registered are: the port to the Network Name Server, the port to the
-@c Environment Manager, and a port to the Service server. These port
-@c values must be placed in specific slots in the init_port_set. The slot
-@c numbers are given by the global constants defined in @file{mach_init.h}:
-@c @code{NAME_SERVER_SLOT}, @code{ENVIRONMENT_SLOT}, and
-@c @code{SERVICE_SLOT}. These ports may later be retrieved with
-@c @code{mach_ports_lookup}.
-
-@c When a new task is created (see @code{task_create}), the child task will
-@c be given access to these ports. Only port send rights may be
-@c registered. Furthermore, the number of ports which may be registered is
-@c fixed and given by the global constant @code{MACH_PORT_SLOTS_USED}
-@c Attempts to register too many ports will fail.
-
-@c It is intended that this mechanism be used only for task initialization,
-@c and then only by runtime support modules. A parent task has three
-@c choices in passing these system ports to a child task. Most commonly it
-@c can do nothing and its child will inherit access to the same
-@c @var{init_port_set} that the parent has; or a parent task may register a
-@c set of ports it wishes to have passed to all of its children by calling
-@c @code{mach_ports_register} using its task port; or it may make necessary
-@c modifications to the set of ports it wishes its child to see, and then
-@c register those ports using the child's task port prior to starting the
-@c child's thread(s). The @code{mach_ports_lookup} call which is done by
-@c @code{mach_init} in the child task will acquire these initial ports for
-@c the child.
-
-@c Tasks other than the Network Name Server and the Environment Manager
-@c should not need access to the Service port. The Network Name Server port
-@c is the same for all tasks on a given machine. The Environment port is
-@c the only port likely to have different values for different tasks.
-
-@c Since the number of ports which may be registered is limited, ports
-@c other than those used by the runtime system to initialize a task should
-@c be passed to children either through an initial message, or through the
-@c Network Name Server for public ports, or the Environment Manager for
-@c private ports.
-
-@c The function returns @code{KERN_SUCCESS} if the memory was allocated,
-@c and @code{KERN_INVALID_ARGUMENT} if an attempt was made to register more
-@c ports than the current kernel implementation allows.
-@c @end deftypefun
+@node Inherited Ports
+@subsection Inherited Ports
+
+The inherited ports concept is not used in the Hurd, and so the _SLOT
+macros are not defined in GNU Mach.
+
+The following section documents how @code{mach_ports_register} and
+@code{mach_ports_lookup} were originally intended to be used.
+
+@deftypefun kern_return_t mach_ports_register (@w{task_t @var{target_task}}, @w{port_array_t @var{init_port_set}}, @w{int @var{init_port_array_count}})
+@deftypefunx kern_return_t mach_ports_lookup (@w{task_t @var{target_task}}, @w{port_array_t *@var{init_port_set}}, @w{int *@var{init_port_array_count}})
+@code{mach_ports_register} manipulates the inherited ports array,
+@code{mach_ports_lookup} is used to acquire specific parent ports.
+@var{target_task} is the task to be affected. @var{init_port_set} is an
+array of system ports to be registered, or returned. Although the array
+size is given as variable, the kernel will only accept a limited number
+of ports. @var{init_port_array_count} is the number of ports returned
+in @var{init_port_set}.
+
+@code{mach_ports_register} registers an array of well-known system ports
+with the kernel on behalf of a specific task. Currently the ports to be
+registered are: the port to the Network Name Server, the port to the
+Environment Manager, and a port to the Service server. These port
+values must be placed in specific slots in the init_port_set. The slot
+numbers are given by the global constants defined in @file{mach_init.h}:
+@code{NAME_SERVER_SLOT}, @code{ENVIRONMENT_SLOT}, and
+@code{SERVICE_SLOT}. These ports may later be retrieved with
+@code{mach_ports_lookup}.
+
+When a new task is created (see @code{task_create}), the child task will
+be given access to these ports. Only port send rights may be
+registered. Furthermore, the number of ports which may be registered is
+fixed and given by the global constant @code{MACH_PORT_SLOTS_USED}
+Attempts to register too many ports will fail.
+
+It is intended that this mechanism be used only for task initialization,
+and then only by runtime support modules. A parent task has three
+choices in passing these system ports to a child task. Most commonly it
+can do nothing and its child will inherit access to the same
+@var{init_port_set} that the parent has; or a parent task may register a
+set of ports it wishes to have passed to all of its children by calling
+@code{mach_ports_register} using its task port; or it may make necessary
+modifications to the set of ports it wishes its child to see, and then
+register those ports using the child's task port prior to starting the
+child's thread(s). The @code{mach_ports_lookup} call which is done by
+@code{mach_init} in the child task will acquire these initial ports for
+the child.
+
+Tasks other than the Network Name Server and the Environment Manager
+should not need access to the Service port. The Network Name Server port
+is the same for all tasks on a given machine. The Environment port is
+the only port likely to have different values for different tasks.
+
+Since the number of ports which may be registered is limited, ports
+other than those used by the runtime system to initialize a task should
+be passed to children either through an initial message, or through the
+Network Name Server for public ports, or the Environment Manager for
+private ports.
+
+The function returns @code{KERN_SUCCESS} if the memory was allocated,
+and @code{KERN_INVALID_ARGUMENT} if an attempt was made to register more
+ports than the current kernel implementation allows.
+@end deftypefun
@node Virtual Memory Interface