X-Git-Url: https://git.saurik.com/apple/launchd.git/blobdiff_plain/ed34e3c3e5fb80e0702ac7fb92f189862089d820..5b0a4722f2ef1eac59c9650b37b29ac8b34a160e:/launchd/src/libbootstrap_public.h diff --git a/launchd/src/libbootstrap_public.h b/launchd/src/libbootstrap_public.h new file mode 100644 index 0000000..b76c52a --- /dev/null +++ b/launchd/src/libbootstrap_public.h @@ -0,0 +1,351 @@ +#ifndef _BOOTSTRAP_H_ +#define _BOOTSTRAP_H_ +/* + * Copyright (c) 1999-2005 Apple Computer, Inc. All rights reserved. + * + * @APPLE_APACHE_LICENSE_HEADER_START@ + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * @APPLE_APACHE_LICENSE_HEADER_END@ + */ + +/* + * bootstrap -- fundamental service initiator and port server + * Mike DeMoney, NeXT, Inc. + * Copyright, 1990. All rights reserved. + */ + +/* + * 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. lookupd, Window Manager, etc...). + * + * Name-port bindings can be established with the bootstrap server by either + * of two mechanisms: + * + * 1. The binding can be indicated, in advance of the service that backs it + * being available, via a "service create" request. 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 an inactive 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. + * + * The bootstrap server may also (re)start server processes associated with + * with a set of services. The definition of the server process is done + * through the "create server" request. The server will be launched in the + * same bootstrap context in which it was registered. + */ +#include +#include +#include +#include +#include +#include + +__BEGIN_DECLS + +#pragma GCC visibility push(default) + +#define BOOTSTRAP_MAX_NAME_LEN 128 +#define BOOTSTRAP_MAX_CMD_LEN 512 + +typedef char name_t[BOOTSTRAP_MAX_NAME_LEN]; +typedef char cmd_t[BOOTSTRAP_MAX_CMD_LEN]; +typedef name_t *name_array_t; +typedef int bootstrap_status_t; +typedef bootstrap_status_t *bootstrap_status_array_t; + +typedef boolean_t *bool_array_t; + +#define BOOTSTRAP_MAX_LOOKUP_COUNT 20 + +#define BOOTSTRAP_SUCCESS 0 +#define BOOTSTRAP_NOT_PRIVILEGED 1100 +#define BOOTSTRAP_NAME_IN_USE 1101 +#define BOOTSTRAP_UNKNOWN_SERVICE 1102 +#define BOOTSTRAP_SERVICE_ACTIVE 1103 +#define BOOTSTRAP_BAD_COUNT 1104 +#define BOOTSTRAP_NO_MEMORY 1105 + +#define BOOTSTRAP_STATUS_INACTIVE 0 +#define BOOTSTRAP_STATUS_ACTIVE 1 +#define BOOTSTRAP_STATUS_ON_DEMAND 2 + +/* + * After main() starts, it is safe to assume that this variable is always set. + */ +extern mach_port_t bootstrap_port; + +/* + * bootstrap_create_server() + * + * Declares a server that mach_init will re-spawn within the specified + * bootstrap context. The server is considered already "active" + * (i.e. will not be re-spawned) until the returned server_port is + * deallocated. + * + * In the meantime, services can be declared against the server, + * by using the server_port as the privileged bootstrap target of + * subsequent bootstrap_create_service() calls. + * + * When mach_init re-spawns the server, its task bootstrap port + * is set to the privileged sever_port. Through this special + * bootstrap port, it can access all of parent bootstrap's context + * (and all services are created in the parent's namespace). But + * all additional service declarations (and declaration removals) + * will be associated with this particular server. + * + * Only a holder of the server_port privilege bootstrap port can + * check in or register over those services. + * + * When all services associated with a server are deleted, and the server + * exits, it will automatically be deleted itself. + * + * If the server is declared "on_demand," then a non-running server + * will be re-launched on first use of one of the service ports + * registered against it. Otherwise, it will be re-launched + * immediately upon exiting (whether any client is actively using + * any of the service ports or not). + * + * Errors: Returns appropriate kernel errors on rpc failure. + * Returns BOOTSTRAP_NOT_PRIVILEGED, bootstrap or uid invalid. + */ +kern_return_t bootstrap_create_server( + mach_port_t bp, + cmd_t server_cmd, + uid_t server_uid, + boolean_t on_demand, + mach_port_t *server_port); + +/* + * bootstrap_subset() + * + * 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 destroyed the subset + * port and all services advertized by it are destroyed as well. + * + * Errors: Returns appropriate kernel errors on rpc failure. + */ +kern_return_t bootstrap_subset( + mach_port_t bp, + mach_port_t requestor_port, + mach_port_t *subset_port); + +/* + * bootstrap_unprivileged() + * + * Given a bootstrap port, return its unprivileged equivalent. If + * the port is already unprivileged, another reference to the same + * port is returned. + * + * This is most often used by servers, which are launched with their + * bootstrap port set to the privileged port for the server, to get + * an unprivileged version of the same port for use by its unprivileged + * children (or any offspring that it does not want to count as part + * of the "server" for mach_init registration and re-launch purposes). + * + * Native launchd jobs are always started with an unprivileged port. + */ +kern_return_t bootstrap_unprivileged( + mach_port_t bp, + mach_port_t *unpriv_port) + AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5; + +/* + * bootstrap_parent() + * + * Given a bootstrap subset port, return the parent bootstrap port. + * If the specified bootstrap port is already the root subset, + * the same port will be returned. Much like "." and ".." are the same + * in the file system name space for the root directory ("/"). + * + * Errors: + * Returns BOOTSTRAP_NOT_PRIVILEGED if the caller is not running + * with an effective user id of root (as determined by the security + * token in the message trailer). + */ +kern_return_t bootstrap_parent( + mach_port_t bp, + mach_port_t *parent_port); + +/* + * bootstrap_register() + * + * Registers a send right for service_port with the service identified by + * service_name. Attempts to register a service where an active binding + * already exists are rejected. + * + * If the service was previously declared with bootstrap_create_service(), + * but is not currently active, this call can be used to undeclare the + * service. The bootstrap port used must have sufficient privilege to + * do so. (Registering MACH_PORT_NULL is especially useful for shutting + * down declared services). + * + * This API is deprecated. Old scenarios and recommendations: + * + * 1) If the code was registering a well known name, please switch to launchd. + * + * 2) If the code was registering a dynamically generated string and passing + * the string to other applications, please rewrite the code to send a Mach + * send-right directly. + * + * 3) If the launchd job maintained an optional Mach service, please reserve + * the name with launchd and control the presense of the service through + * ownership of the Mach receive right like so. + * + * MachServices + * + * com.apple.windowserver + * + * com.apple.windowserver.active + * + * HideUntilCheckIn + * + * + * + * + * + * 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. + */ +kern_return_t bootstrap_register( + mach_port_t bp, + name_t service_name, + mach_port_t sp) + AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5; + +/* + * bootstrap_create_service() + * + * 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. + */ +kern_return_t bootstrap_create_service( + mach_port_t bp, + name_t service_name, + mach_port_t *sp); + +/* + * bootstrap_check_in() + * + * Returns the receive right for the service named by service_name. The + * service must have previously been declared in this bootstrap context via + * a call to bootstrap_create_service(). Attempts to check_in a service + * which is already active are not allowed. + * + * If the service was declared as being associated with a server, the + * check_in must come from the server's privileged port (server_port). + * + * 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. + */ +kern_return_t bootstrap_check_in( + mach_port_t bp, + name_t service_name, + mach_port_t *sp); + +/* + * bootstrap_look_up() + * + * Returns a send right for the service port declared/registered under the + * name service_name. The service is not guaranteed to be active. Use the + * bootstrap_status call to determine the status of the service. + * + * Errors: Returns appropriate kernel errors on rpc failure. + * Returns BOOTSTRAP_UNKNOWN_SERVICE, if service does not exist. + */ +kern_return_t bootstrap_look_up( + mach_port_t bp, + name_t service_name, + mach_port_t *sp); + +/* + * bootstrap_status() + * + * In practice, this call was used to preflight whether the following two + * APIs would succeed. + * + * bootstrap_look_up() + * bootstrap_check_in() + * + * Please don't bother. Just call the above two APIs directly and check + * for failure. + */ +kern_return_t bootstrap_status( + mach_port_t bp, + name_t service_name, + bootstrap_status_t *service_active) + AVAILABLE_MAC_OS_X_VERSION_10_0_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_5; + +/* bootstrap_strerror() + * + * Translate a return value from the bootstrap_*() APIs to a string. + */ +const char *bootstrap_strerror(kern_return_t r) __attribute__((__nothrow__, __pure__, __warn_unused_result__)); + +#pragma GCC visibility pop + +__END_DECLS + +#endif