home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.0 / NeXTSTEP3.0.iso / NextDeveloper / Headers / servers / bootstrap.defs < prev    next >
Text File  |  1991-08-07  |  11KB  |  306 lines
  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.  
  9. subsystem bootstrap 400;
  10.  
  11. /*
  12.  *    Interface:    Boot(`p 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 d(at 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:(brings 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>
  125. import <servers/bootstrap_defs.h>;
  126.  
  127. type name_t        = (MSG_TYPE_STRING,8*128);
  128. type name_array_t    = ^array [] of name_t;
  129. type bool_array_t    = ^array [] of boolean_t;
  130.  
  131. serverprefix x_;
  132.  
  133. /*  old service_checkin */
  134. skip;
  135. /*  old service_status */
  136. skip;
  137.  
  138. /*
  139.  * kern_return_t
  140.  * bootstrap_check_in(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.  */
  153. routine bootstrap_check_in(
  154.             bootstrap_port    : port_t;
  155.             service_name    : name_t;
  156.         out    service_port    : port_all_t);
  157.  
  158. /*
  159.  * kern_return_t
  160.  * bootstrap_register(port_t bootstrap_port,
  161.  *              name_t service_name,
  162.  *              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.  */
  179. routine bootstrap_register(
  180.         bootstrap_port    : port_t;
  181.         service_name    : name_t;
  182.         service_port    : port_t)(c*
  183.  * kern_return_t
  184.  * bootstrap_look_up(port_t bootstrap_port,
  185.  *            name_t service_name,
  186.  *            port_t *service_port)
  187.  *
  188.  * Returns send rights for the service port of the service named by
  189.  * service_name in service_port.  Service is not guaranteed to be active.
  190.  *
  191.  * Errors:    Returns appropriate kernel errors on rpc failure.
  192.  *        Returns BOOTSTRAP_UNKNOWN_SERVICE, if service does not exist.
  193.  */
  194. routine bootstrap_look_up(
  195.         bootstrap_port    : port_t;
  196.         service_name    : name_t;
  197.     out    service_port    : port_t);
  198.  
  199. /*
  200.  * kern_return_t
  201.  * bootstrap_look_up_array(port_t bootstrap_port,
  202.  *              name_array_t service_names,
  203.  *              int service_names_cnt,
  204.  *              port_array_t *service_port,
  205.  *              int *service_ports_cnt,
  206.  *              boolean_t *all_services_known)
  207.  *
  208.  * Returns port send rights in corresponding entries of the array service_ports
  209.  * for all services named in the array service_names.  Service_ports_cnt is
  210.  * returned and will always equal service_names_cnt (assuming service_names_cnt
  211.  * is greater than or equal to zero).
  212.  *
  213.  * Errors:    Returns appropriate kernel errors on rpc failure.
  214.  *        Returns BOOTSTRAP_NO_MEMORY, if server couldn't obtain memory
  215.  *            for response.
  216.  *        Unknown service names have the corresponding service port set
  217.  *            to PORT_NULL.
  218.  *        If all services are known, all_services_known is true on
  219.  *            return, if any service is unknown, it's false.
  220.  */
  221. routine bootstrap_look_up_array(
  222.         bootstrap_port    : port_t;
  223.         service_names    : name_array_t;
  224.     out    service_ports    : port_array_t;
  225.     out    all_services_known: boolean_t);
  226.  
  227. /*  old bootstrap_get_unpriv_port */
  228. skip;
  229.  
  230. /*
  231.  * kern_return_t
  232.  * bootstrap_status(port_t bootstrap_port,
  233.  *            name_t service_name,
  234.  *            boolean_t *service_active);
  235.  *
  236.  * Returns: service_active is true if service is available.
  237.  *            
  238.  * Errors:    Returns appropriate kernel errors on rpc failure.
  239.  *        Returns BOOTSTRAP_UNKNOWN_SERVICE, if service does not exist.
  240.  */
  241. routine bootstrap_status(
  242.         bootstrap_port    :    port_t;
  243.         service_name    :    name_t;
  244.     out    service_active    :    boolean_t);
  245.  
  246. /*
  247.  * kern_return_t
  248.  * bootstrap_info(port_t bootstrap_port,
  249.  *          name_array_t *service_names,
  250.  *          int *service_names_cnt,
  251.  *          name_array_t *server_names,
  252.  *          int *server_names_cnt,
  253.  *          bool_array_t *service_active,
  254.  *          int *service_active_cnt);
  255.  *            
  256.  * Errors:    Returns appropriate kernel errors on rpc failure.
  257.  */
  258. routine bootstrap_info(
  259.         bootstrap_port    : port_t;
  260.     out    service_names    : name_array_t, dealloc;
  261.     out server_names    : name_array_t, dealloc;
  262.     out service_active    : bool_array_t, dealloc);
  263.  
  264. /*
  265.  * kern_return_t
  266.  * bootstrap(Xset(port_t bootstrap_port,
  267.  *            port_t requestor_port,
  268.  *            port_t *subset_port);
  269.  *
  270.  * Returns a new port to use as a bootstrap port.  This port behaves
  271.  * exactly like the previous bootstrap_port, except that ports dynamically
  272.  * registered via bootstrap_register() are available only to users of this
  273.  * specific subset_port.  Lookups on the subset_port will return ports
  274.  * registered with this port specifically, and ports registered with
  275.  * ancestors of this subset_port.  Duplications of services already
  276.  * registered with an ancestor port may be registered with the subset port
  277.  * are allowed.  Services already advertised may then be effectively removed
  278.  * by registering PORT_NULL for the service.
  279.  * When it is detected that the requestor_port is destroied the subset
  280.  * port and all services advertized by it are destroied as well.
  281.  *
  282.  * Errors:    Returns appropriate kernel errors on rpc failure.
  283.  */
  284. routine bootstrap_subset(
  285.         bootstrap_port    : port_t;
  286.         requestor_port    : port_t;
  287.     out    subset_port    : port_t);
  288.  
  289. /*
  290.  * kern_return_t
  291.  * bootstrap_create_service(port_t bootstrap_port,
  292.  *              name_t service_name,
  293.  *              port_t *service_port)
  294.  *
  295.  * Creates a service named "service_name" and returns send rights to that
  296.  * port in "service_port."  The port may later be checked in as if this
  297.  * port were configured in the bootstrap configuration file.
  298.  *
  299.  * Errors:    Returns appropriate kernel errors on rpc failure.
  300.  *        Returns BOOTSTRAP_SERVICE_ACTIVE, if service already exists.
  301.  */
  302. routine bootstrap_create_service(
  303.         bootstrap_port    : port_t;
  304.         service_name    : name_t;
  305.     out    service_port    : port_t);
  306.