1 .\"
2 .\" Mach Operating System
3 .\" Copyright (c) 1991,1990 Carnegie Mellon University
4 .\" All Rights Reserved.
5 .\"
6 .\" Permission to use, copy, modify and distribute this software and its
7 .\" documentation is hereby granted, provided that both the copyright
8 .\" notice and this permission notice appear in all copies of the
9 .\" software, derivative works or modified versions, and any portions
10 .\" thereof, and that both notices appear in supporting documentation.
11 .\"
12 .\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
13 .\" CONDITION. CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
14 .\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
15 .\"
16 .\" Carnegie Mellon requests users of this software to return to
17 .\"
18 .\" Software Distribution Coordinator or Software.Distribution@CS.CMU.EDU
19 .\" School of Computer Science
20 .\" Carnegie Mellon University
21 .\" Pittsburgh PA 15213-3890
22 .\"
23 .\" any improvements or extensions that they make and grant Carnegie Mellon
24 .\" the rights to redistribute these changes.
25 .\"
26 .\"
27 .\" HISTORY
28 .\" $Log: mach_ports_register.man,v $
29 .\" Revision 2.2 93/05/10 19:33:06 rvb
30 .\" updated
31 .\" [93/04/21 16:07:08 lli]
32 .\"
33 .\" Revision 2.4 91/05/14 17:07:59 mrt
34 .\" Correcting copyright
35 .\"
36 .\" Revision 2.3 91/02/14 14:12:14 mrt
37 .\" Changed to new Mach copyright
38 .\" [91/02/12 18:12:24 mrt]
39 .\"
40 .\" Revision 2.2 90/08/07 18:38:36 rpd
41 .\" Created.
42 .\"
43 .TH mach_ports 2 9/19/86
44 .CM 4
45 .SH NAME
46 .nf
47 mach_ports_register \- manipulate the inherited ports array
48 mach_ports_lookup \- child port acquires specific parent ports
49 .SH SYNOPSIS
50 .nf
51 .ft B
52 #include <mach.h>
53
54 .nf
55 .ft B
56 kern_return_t mach_ports_register(target_task,
57 init_port_set, init_port_array_count)
58 mach_port_t target_task;
59 port_array_t init_port_set; /* array */
60 mach_msg_type_number_t* init_port_array_count;
61
62
63 .fi
64 .ft P
65 .nf
66 .ft B
67 kern_return_t mach_ports_lookup(target_task,
68 init_port_set, init_port_array_count)
69 mach_port_t target_task;
70 port_array_t *init_port_set; /* out array */
71 mach_msg_type_number_t* *init_port_array_count; /* out */
72
73
74 .fi
75 .ft P
76 .SH ARGUMENTS
77 .TP 15
78 .B
79 target_task
80 Task to be affected.
81 .TP 15
82 .B
83 init_port_set
84 An array of system ports to be registered, or returned.
85 Although the array size is given as variable, the kernel will only accept a limited number of ports.
86 .TP 15
87 .B
88 init_port_array_count
89 The number of ports returned in
90 .B init_port_set.
91
92 .SH DESCRIPTION
93 .B mach_ports_register
94 registers an array of well-known system ports with the
95 kernel on behalf of a specific task. Currently the ports to be
96 registered are: the port to the Network Name Server, the port to the Environment
97 Manager, and a port to the Service server. These port values must be placed
98 in specific slots in the
99 .B init_port_set.
100 The slot numbers are given by the
101 global constants defined in
102 .B mach_init.h
103 :
104 .B NAME_SERVER_SLOT
105 ,
106 .B ENVIRONMENT_SLOT
107 ,
108 and
109 .B SERVICE_SLOT.
110 These
111 ports may later be retrieved with
112 .B mach_ports_lookup.
113
114 When a new task is created (see
115 .B task_create
116 ), the
117 child task will be given access to these ports.
118 Only port send rights may be registered.
119 Furthermore, the number of ports which may be registered is
120 fixed and given by the global constant
121 .B MACH_PORT_SLOTS_USED
122 .
123 Attempts to register too many ports will fail.
124
125 It is intended that this mechanism be used only for task
126 initialization, and then only by runtime support modules.
127 A parent task has three choices in passing these system ports to
128 a child task. Most commonly it can do nothing and its child will
129 inherit access to the same
130 .B init_port_set
131 that the parent has;
132 or a parent task may register a set of ports it wishes to have passed
133 to all of its children by calling
134 .B mach_ports_register
135 using
136 its task port; or it may make necessary modifications
137 to the set of ports it wishes its child to see, and then register
138 those ports using the child's task port prior to starting the
139 child's thread(s).
140 The
141 .B mach_ports_lookup
142 call which is done by
143 .B mach_init
144 in the child task will acquire these initial ports
145 for the child.
146
147 Tasks other than the Network Name Server and the
148 Environment Mangager should not need access to the Service port. The Network
149 Name Server port is the same for all tasks on a given machine. The Environment port
150 is the only port likely to have different values for different tasks.
151
152 Since the number of ports which may be registered is limited,
153 ports other than those used by the runtime system to initialize
154 a task should be passed to children either through an initial
155 message, or through the Network Name Server for public ports,
156 or the Environment Manager for private ports.
157
158 .SH DIAGNOSTICS
159 .TP 25
160 KERN_SUCCESS
161 Memory allocated.
162 .TP 25
163 KERN_INVALID_ARGUMENT
164 An attempt was made to register more ports than the
165 current kernel implementation allows.
166
167 .SH SEE ALSO
168 .B mach_init, netname, env_mgr, service
169
Cache object: 22471e59c1617d0b620f520047c4aa48
|