Libc-166.tar.gz
[apple/libc.git] / mach.subproj / servers.subproj / bootstrap.defs
CommitLineData
e9ce8d39
A
1/*
2 * bootstrap -- fundamental service initiator and port server
3 * Mike DeMoney, NeXT, Inc.
4 * Copyright, 1990. All rights reserved.
5 *
6 * bootstrap.defs -- Mig interface definition
7 */
8
9subsystem bootstrap 400;
10
11/*
12 * Interface: Bootstrap server
13 *
14 * The bootstrap server is the first user-mode task initiated by the Mach
15 * kernel at system boot time. The bootstrap server provides two services,
16 * it initiates other system tasks, and manages a table of name-port bindings
17 * for fundamental system services (e.g. the NetMsgServer, and the Unix
18 * emulation service).
19 *
20 * The file /etc/bootstrap.conf is read by bootstrap to determine other system
21 * services to initiate at system boot time. The format of this file is
22 * described later.
23 *
24 * Name-port bindings can be established with the bootstrap server by either
25 * of two mechanisms:
26 *
27 * 1. The binding can be indicated in the file /etc/bootstrap.conf. In this
28 * case, bootstrap will immediately create a port and bind the indicated name
29 * with that port. At a later time, a service may "checkin" for the name-port
30 * binding and will be returned receive rights for the bound port. Lookup's
31 * on bindings created by this mechanism will return send rights to the port,
32 * even if no service has "checked-in". In this case, requests sent to the
33 * bound port will be queued until a server has checked-in and can satisfy the
34 * request.
35 *
36 * 2. Bindings can be established dynamically via a "register" request. In
37 * this case, the register request provides bootstrap with a name and send
38 * rights for a port. Bootstrap will provide send rights for the bound port
39 * to any requestor via the lookup request.
40 *
41 * Bootstrap provides its service port to descendant tasks via the Mach
42 * "bootstrap" special task port. All direct descendants of bootstrap receive
43 * a "privileged" bootstrap service port. System services that initiate
44 * untrusted tasks should replace the Mach bootstrap task special port with
45 * a subset bootstrap port to prevent them from infecting the namespace.
46 *
47 * The bootstrap server creates a "backup" port for each service that it
48 * creates. This is used to detect when a checked out service is no longer
49 * being served. The bootstrap server regains all rights to the port and
50 * it is marked available for check-out again. This allows crashed servers to
51 * resume service to previous clients. Lookup's on this named port will
52 * continue to be serviced by bootstrap while holding receive rights for the
53 * bound port. A client may detect that the service is inactive via the.
54 * bootstrap status request. If the service re-registers rather than
55 * "checking-in" the original bound port is destroyed.
56 *
57 * The status of a named service may be obtained via the "status" request.
58 * A service is "active" if a name-port binding exists and receive rights
59 * to the bound port are held by a task other than bootstrap.
60 *
61 * Bootstrap initiates server tasks and creates initial name-port bindings as
62 * directed by the configuration file /etc/bootstrap.conf. This file has
63 * entries with the following formats:
64 *
65 * services [ SERVICE_NAME ]+ ;
66 *
67 * E.g:
68 * services OldService=1 SomeService;
69 *
70 * Creates a port and binds the name "OldService" to it.
71 * For compatability, assigns the port via mach_ports_register to
72 * slot 1. Also creates a port and binds the name "SomeService".
73 *
74 * self [ SERVICE_NAME ]+ ;
75 *
76 * E.g:
77 * self BootStrapService;
78 *
79 * Provides a binding to bootstrap's own service port named
80 * "BootStrapService".
81 *
82 * [restartable] server SERVER_FILE_AND_ARGS [ services ... ] ;
83 *
84 * E.g:
85 * server "/usr/etc/sigserver -i" services UnixSignalService;
86 *
87 * Initiates the server task "/usr/etc/sigserver" with
88 * command-line argument "-i", and also creates a name-port
89 * binding for the name UnixSignalService. Checkin requests for
90 * UnixSignalService are only accepted via the bootstrap service
91 * port passed to/usr/etc/sigserver. If the "restartable" option
92 * had been specified, bootstrap will reinitiate the server task
93 * if it receives notification that all of the server's service
94 * ports have been destroyed or deallocated. The server command
95 * may be specified without surrounding quotes if it does not
96 * include blanks.
97 *
98 * init SERVER_FILE_AND_ARGS [ services ... ] ;
99 *
100 * E.g:
101 * init /etc/init services NetMsgService=0 PSWindowService=4;
102 *
103 * Functions like "server" request above, except process is
104 * started as pid 1. Illegal if bootstrap itself was not
105 * initiated as pid 1.
106 *
107 * forward;
108 *
109 * If present, bootstrap will forward unknown lookup requests to
110 * its bootstrap service port (if not PORT_NULL), and forward any
111 * reply to the original requester.
112 *
113 * # Comment string up to end of line.
114 *
115 * A line terminated comment starts with a sharp sign (#).
116 *
117 * Lexical notes: Strings are either enclosed in double quotes ("), or must
118 * start with a letter or underscore (_) and followed by a string of
119 * alphanumerics and underscores; backslash (\) escapes the following
120 * character. Strings are limited to a (large) length. Numbers must be
121 * decimal. Blanks and newlines may be freely used outside of strings.
122 */
123
124#include <mach/std_types.defs>
125import <servers/bootstrap_defs.h>;
126
127type name_t = c_string[128];
128type name_array_t = ^array [] of name_t;
129type bool_array_t = ^array [] of boolean_t;
130
131serverprefix x_;
132
133/* old service_checkin */
134skip;
135/* old service_status */
136skip;
137
138/*
139 * kern_return_t
140 * bootstrap_check_in(mach_port_t bootstrap_port,
141 * name_t service_name,
142 * port_all_t *service_port)
143 *
144 * Returns all rights to service_port of service named by service_name.
145 *
146 * Errors: Returns appropriate kernel errors on rpc failure.
147 * Returns BOOTSTRAP_UNKNOWN_SERVICE, if service does not exist.
148 * Returns BOOTSTRAP_NOT_PRIVILEGED, if request directed to
149 * bootstrap port without privilege.
150 * Returns BOOTSTRAP_SERVICE_ACTIVE, if service has already been
151 * registered or checked-in.
152 */
153routine bootstrap_check_in(
154 bootstrap_port : mach_port_t;
155 service_name : name_t;
156 out service_port : mach_port_move_receive_t);
157
158/*
159 * kern_return_t
160 * bootstrap_register(mach_port_t bootstrap_port,
161 * name_t service_name,
162 * mach_port_t service_port)
163 *
164 * Registers send rights for the port service_port for the service named by
165 * service_name. Attempts to registering a service where an active binding
166 * already exists are rejected. On the otherhand, registering a service where
167 * and inactive binding exists (i.e. bootstrap currently holds receive rights
168 * for the service port) is allowed; in this case the previous service port
169 * will be deallocated. Restarting services wishing to resume service for
170 * previous clients must first attempt to checkin to the service in order to
171 * recover the previous service port.
172 *
173 * Errors: Returns appropriate kernel errors on rpc failure.
174 * Returns BOOTSTRAP_NOT_PRIVILEGED, if request directed to
175 * bootstrap port without privilege.
176 * Returns BOOTSTRAP_NAME_IN_USE, if service has already been
177 * register or checked-in.
178 */
179routine bootstrap_register(
180 bootstrap_port : mach_port_t;
181 service_name : name_t;
182 service_port : mach_port_t);
183
184/*
185 * kern_return_t
186 * bootstrap_look_up(mach_port_t bootstrap_port,
187 * name_t service_name,
188 * mach_port_t *service_port)
189 *
190 * Returns send rights for the service port of the service named by
191 * service_name in service_port. Service is not guaranteed to be active.
192 *
193 * Errors: Returns appropriate kernel errors on rpc failure.
194 * Returns BOOTSTRAP_UNKNOWN_SERVICE, if service does not exist.
195 */
196routine bootstrap_look_up(
197 bootstrap_port : mach_port_t;
198 service_name : name_t;
199 out service_port : mach_port_t);
200
201/*
202 * kern_return_t
203 * bootstrap_look_up_array(mach_port_t bootstrap_port,
204 * name_array_t service_names,
205 * int service_names_cnt,
206 * port_array_t *service_port,
207 * int *service_ports_cnt,
208 * boolean_t *all_services_known)
209 *
210 * Returns port send rights in corresponding entries of the array service_ports
211 * for all services named in the array service_names. Service_ports_cnt is
212 * returned and will always equal service_names_cnt (assuming service_names_cnt
213 * is greater than or equal to zero).
214 *
215 * Errors: Returns appropriate kernel errors on rpc failure.
216 * Returns BOOTSTRAP_NO_MEMORY, if server couldn't obtain memory
217 * for response.
218 * Unknown service names have the corresponding service port set
219 * to PORT_NULL.
220 * If all services are known, all_services_known is true on
221 * return, if any service is unknown, it's false.
222 */
223routine bootstrap_look_up_array(
224 bootstrap_port : mach_port_t;
225 service_names : name_array_t;
226 out service_ports : mach_port_array_t;
227 out all_services_known: boolean_t);
228
229/* old bootstrap_get_unpriv_port */
230skip;
231
232/*
233 * kern_return_t
234 * bootstrap_status(mach_port_t bootstrap_port,
235 * name_t service_name,
236 * boolean_t *service_active);
237 *
238 * Returns: service_active is true if service is available.
239 *
240 * Errors: Returns appropriate kernel errors on rpc failure.
241 * Returns BOOTSTRAP_UNKNOWN_SERVICE, if service does not exist.
242 */
243routine bootstrap_status(
244 bootstrap_port : mach_port_t;
245 service_name : name_t;
246 out service_active : boolean_t);
247
248/*
249 * kern_return_t
250 * bootstrap_info(port_t bootstrap_port,
251 * name_array_t *service_names,
252 * int *service_names_cnt,
253 * name_array_t *server_names,
254 * int *server_names_cnt,
255 * bool_array_t *service_active,
256 * int *service_active_cnt);
257 *
258 * Errors: Returns appropriate kernel errors on rpc failure.
259 */
260routine bootstrap_info(
261 bootstrap_port : mach_port_t;
262 out service_names : name_array_t, dealloc;
263 out server_names : name_array_t, dealloc;
264 out service_active : bool_array_t, dealloc);
265
266/*
267 * kern_return_t
268 * bootstrap_subset(mach_port_t bootstrap_port,
269 * mach_port_t requestor_port,
270 * mach_port_t *subset_port);
271 *
272 * Returns a new port to use as a bootstrap port. This port behaves
273 * exactly like the previous bootstrap_port, except that ports dynamically
274 * registered via bootstrap_register() are available only to users of this
275 * specific subset_port. Lookups on the subset_port will return ports
276 * registered with this port specifically, and ports registered with
277 * ancestors of this subset_port. Duplications of services already
278 * registered with an ancestor port may be registered with the subset port
279 * are allowed. Services already advertised may then be effectively removed
280 * by registering PORT_NULL for the service.
281 * When it is detected that the requestor_port is destroied the subset
282 * port and all services advertized by it are destroied as well.
283 *
284 * Errors: Returns appropriate kernel errors on rpc failure.
285 */
286routine bootstrap_subset(
287 bootstrap_port : mach_port_t;
288 requestor_port : mach_port_t;
289 out subset_port : mach_port_t);
290
291/*
292 * kern_return_t
293 * bootstrap_create_service(mach_port_t bootstrap_port,
294 * name_t service_name,
295 * mach_port_t *service_port)
296 *
297 * Creates a service named "service_name" and returns send rights to that
298 * port in "service_port." The port may later be checked in as if this
299 * port were configured in the bootstrap configuration file.
300 *
301 * Errors: Returns appropriate kernel errors on rpc failure.
302 * Returns BOOTSTRAP_SERVICE_ACTIVE, if service already exists.
303 */
304routine bootstrap_create_service(
305 bootstrap_port : mach_port_t;
306 service_name : name_t;
307 out service_port : mach_port_t);