/*
* bootstrap -- fundamental service initiator and port server
* Mike DeMoney, NeXT, Inc.
* Copyright, 1990. All rights reserved.
*
* bootstrap.defs -- Mig interface definition
*/
subsystem bootstrap 400;
/*
* Interface: Bootstrap server
*
* The bootstrap server is the first user-mode task initiated by the Mach
* kernel at system boot time. The bootstrap server provides two services,
* it initiates other system tasks, and manages a table of name-port bindings
* for fundamental system services (e.g. the NetMsgServer, and the Unix
* emulation service).
*
* The file /etc/bootstrap.conf is read by bootstrap to determine other system
* services to initiate at system boot time. The format of this file is
* described later.
*
* Name-port bindings can be established with the bootstrap server by either
* of two mechanisms:
*
* 1. The binding can be indicated in the file /etc/bootstrap.conf. In this
* case, bootstrap will immediately create a port and bind the indicated name
* with that port. At a later time, a service may "checkin" for the name-port
* binding and will be returned receive rights for the bound port. Lookup's
* on bindings created by this mechanism will return send rights to the port,
* even if no service has "checked-in". In this case, requests sent to the
* bound port will be queued until a server has checked-in and can satisfy the
* request.
*
* 2. Bindings can be established dynamically via a "register" request. In
* this case, the register request provides bootstrap with a name and send
* rights for a port. Bootstrap will provide send rights for the bound port
* to any requestor via the lookup request.
*
* Bootstrap provides its service port to descendant tasks via the Mach
* "bootstrap" special task port. All direct descendants of bootstrap receive
* a "privileged" bootstrap service port. System services that initiate
* untrusted tasks should replace the Mach bootstrap task special port with
* a subset bootstrap port to prevent them from infecting the namespace.
*
* The bootstrap server creates a "backup" port for each service that it
* creates. This is used to detect when a checked out service is no longer
* being served. The bootstrap server regains all rights to the port and
* it is marked available for check-out again. This allows crashed servers to
* resume service to previous clients. Lookup's on this named port will
* continue to be serviced by bootstrap while holding receive rights for the
* bound port. A client may detect that the service is inactive via the.
* bootstrap status request. If the service re-registers rather than
* "checking-in" the original bound port is destroyed.
*
* The status of a named service may be obtained via the "status" request.
* A service is "active" if a name-port binding exists and receive rights
* to the bound port are held by a task other than bootstrap.
*
* Bootstrap initiates server tasks and creates initial name-port bindings as
* directed by the configuration file /etc/bootstrap.conf. This file has
* entries with the following formats:
*
* services [ SERVICE_NAME ]+ ;
*
* E.g:
* services OldService=1 SomeService;
*
* Creates a port and binds the name "OldService" to it.
* For compatability, assigns the port via mach_ports_register to
* slot 1. Also creates a port and binds the name "SomeService".
*
* self [ SERVICE_NAME ]+ ;
*
* E.g:
* self BootStrapService;
*
* Provides a binding to bootstrap's own service port named
* "BootStrapService".
*
* [restartable] server SERVER_FILE_AND_ARGS [ services ... ] ;
*
* E.g:
* server "/usr/etc/sigserver -i" services UnixSignalService;
*
* Initiates the server task "/usr/etc/sigserver" with
* command-line argument "-i", and also creates a name-port
* binding for the name UnixSignalService. Checkin requests for
* UnixSignalService are only accepted via the bootstrap service
* port passed to/usr/etc/sigserver. If the "restartable" option
* had been specified, bootstrap will reinitiate the server task
* if it receives notification that all of the server's service
* ports have been destroyed or deallocated. The server command
* may be specified without surrounding quotes if it does not
* include blanks.
*
* init SERVER_FILE_AND_ARGS [ services ... ] ;
*
* E.g:
* init /etc/init services NetMsgService=0 PSWindowService=4;
*
* Functions like "server" request above, except process is
* started as pid 1. Illegal if bootstrap itself was not
* initiated as pid 1.
*
* forward;
*
* If present, bootstrap will forward unknown lookup requests to
* its bootstrap service port (if not PORT_NULL), and forward any
* reply to the original requester.
*
* # Comment string up to end of line.
*
* A line terminated comment starts with a sharp sign (#).
*
* Lexical notes: Strings are either enclosed in double quotes ("), or must
* start with a letter or underscore (_) and followed by a string of
* alphanumerics and underscores; backslash (\) escapes the following
* character. Strings are limited to a (large) length. Numbers must be
* decimal. Blanks and newlines may be freely used outside of strings.
*/
#include <mach/std_types.defs>
import <servers/bootstrap_defs.h>;
type name_t = c_string[128];
type name_array_t = ^array [] of name_t;
type bool_array_t = ^array [] of boolean_t;
serverprefix x_;
/* old service_checkin */
skip;
/* old service_status */
skip;
/*
* kern_return_t
* bootstrap_check_in(mach_port_t bootstrap_port,
* name_t service_name,
* port_all_t *service_port)
*
* Returns all rights to service_port of service named by service_name.
*
* Errors: Returns appropriate kernel errors on rpc failure.
* Returns BOOTSTRAP_UNKNOWN_SERVICE, if service does not exist.
* Returns BOOTSTRAP_NOT_PRIVILEGED, if request directed to
* bootstrap port without privilege.
* Returns BOOTSTRAP_SERVICE_ACTIVE, if service has already been
* registered or checked-in.
*/
routine bootstrap_check_in(
bootstrap_port : mach_port_t;
service_name : name_t;
out service_port : mach_port_move_receive_t);
/*
* kern_return_t
* bootstrap_register(mach_port_t bootstrap_port,
* name_t service_name,
* mach_port_t service_port)
*
* Registers send rights for the port service_port for the service named by
* service_name. Attempts to registering a service where an active binding
* already exists are rejected. On the otherhand, registering a service where
* and inactive binding exists (i.e. bootstrap currently holds receive rights
* for the service port) is allowed; in this case the previous service port
* will be deallocated. Restarting services wishing to resume service for
* previous clients must first attempt to checkin to the service in order to
* recover the previous service port.
*
* Errors: Returns appropriate kernel errors on rpc failure.
* Returns BOOTSTRAP_NOT_PRIVILEGED, if request directed to
* bootstrap port without privilege.
* Returns BOOTSTRAP_NAME_IN_USE, if service has already been
* register or checked-in.
*/
routine bootstrap_register(
bootstrap_port : mach_port_t;
service_name : name_t;
service_port : mach_port_t);
/*
* kern_return_t
* bootstrap_look_up(mach_port_t bootstrap_port,
* name_t service_name,
* mach_port_t *service_port)
*
* Returns send rights for the service port of the service named by
* service_name in service_port. Service is not guaranteed to be active.
*
* Errors: Returns appropriate kernel errors on rpc failure.
* Returns BOOTSTRAP_UNKNOWN_SERVICE, if service does not exist.
*/
routine bootstrap_look_up(
bootstrap_port : mach_port_t;
service_name : name_t;
out service_port : mach_port_t);
/*
* kern_return_t
* bootstrap_look_up_array(mach_port_t bootstrap_port,
* name_array_t service_names,
* int service_names_cnt,
* port_array_t *service_port,
* int *service_ports_cnt,
* boolean_t *all_services_known)
*
* Returns port send rights in corresponding entries of the array service_ports
* for all services named in the array service_names. Service_ports_cnt is
* returned and will always equal service_names_cnt (assuming service_names_cnt
* is greater than or equal to zero).
*
* Errors: Returns appropriate kernel errors on rpc failure.
* Returns BOOTSTRAP_NO_MEMORY, if server couldn't obtain memory
* for response.
* Unknown service names have the corresponding service port set
* to PORT_NULL.
* If all services are known, all_services_known is true on
* return, if any service is unknown, it's false.
*/
routine bootstrap_look_up_array(
bootstrap_port : mach_port_t;
service_names : name_array_t;
out service_ports : mach_port_array_t;
out all_services_known: boolean_t);
/* old bootstrap_get_unpriv_port */
skip;
/*
* kern_return_t
* bootstrap_status(mach_port_t bootstrap_port,
* name_t service_name,
* boolean_t *service_active);
*
* Returns: service_active is true if service is available.
*
* Errors: Returns appropriate kernel errors on rpc failure.
* Returns BOOTSTRAP_UNKNOWN_SERVICE, if service does not exist.
*/
routine bootstrap_status(
bootstrap_port : mach_port_t;
service_name : name_t;
out service_active : boolean_t);
/*
* kern_return_t
* bootstrap_info(port_t bootstrap_port,
* name_array_t *service_names,
* int *service_names_cnt,
* name_array_t *server_names,
* int *server_names_cnt,
* bool_array_t *service_active,
* int *service_active_cnt);
*
* Errors: Returns appropriate kernel errors on rpc failure.
*/
routine bootstrap_info(
bootstrap_port : mach_port_t;
out service_names : name_array_t, dealloc;
out server_names : name_array_t, dealloc;
out service_active : bool_array_t, dealloc);
/*
* kern_return_t
* bootstrap_subset(mach_port_t bootstrap_port,
* mach_port_t requestor_port,
* mach_port_t *subset_port);
*
* Returns a new port to use as a bootstrap port. This port behaves
* exactly like the previous bootstrap_port, except that ports dynamically
* registered via bootstrap_register() are available only to users of this
* specific subset_port. Lookups on the subset_port will return ports
* registered with this port specifically, and ports registered with
* ancestors of this subset_port. Duplications of services already
* registered with an ancestor port may be registered with the subset port
* are allowed. Services already advertised may then be effectively removed
* by registering PORT_NULL for the service.
* When it is detected that the requestor_port is destroied the subset
* port and all services advertized by it are destroied as well.
*
* Errors: Returns appropriate kernel errors on rpc failure.
*/
routine bootstrap_subset(
bootstrap_port : mach_port_t;
requestor_port : mach_port_t;
out subset_port : mach_port_t);
/*
* kern_return_t
* bootstrap_create_service(mach_port_t bootstrap_port,
* name_t service_name,
* mach_port_t *service_port)
*
* Creates a service named "service_name" and returns send rights to that
* port in "service_port." The port may later be checked in as if this
* port were configured in the bootstrap configuration file.
*
* Errors: Returns appropriate kernel errors on rpc failure.
* Returns BOOTSTRAP_SERVICE_ACTIVE, if service already exists.
*/
routine bootstrap_create_service(
bootstrap_port : mach_port_t;
service_name : name_t;
out service_port : mach_port_t);