home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / mach / doc / unpublished / envmgr.doc.Z / envmgr.doc
Encoding:
Text File  |  1992-09-01  |  16.0 KB  |  488 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.                            MACH ENVIRONMENT MANAGER
  13.  
  14.                                Mary R. Thompson
  15.  
  16.                         Department of Computer Science
  17.                           Carnegie-Mellon University
  18.                              Pittsburgh, PA 15213
  19.                                   Version of:
  20.                                  4 August 1989
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.                                    ABSTRACT
  39.  
  40. The  Environment Manager is a Mach server which facilities the sharing of named
  41. variables between tasks.
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.   This research was sponsored by the Defense Advanced Research Projects  Agency
  53. (DOD),  ARPA  Order  No. 4864, monitored by the Space and Naval Warfare Systems
  54. Command under contract N00039-84-C-0467.
  55.  
  56.   The views and conclusions contained in this document are those of the authors
  57. and  should  not  be  interpreted  as  representing  official  policies, either
  58. expressed or implied, of the Defense Advanced Research Projects  Agency  or  of
  59. the U.S.  Government.
  60. 1. Introduction
  61.   The  Environment  Manager  is a server which facilitates the sharing of named
  62. variables between tasks. An environment is a set of named variables, which  can
  63. be  read  or changed via calls on an Environment Port. A single environment may
  64. be shared between parent and child tasks, or an environment can be copied,  and
  65. a  copy  can  be passed to a child task. It is also possible to get a read-only
  66. port to an environment  which  allows  reading  but  not  modification  of  the
  67. environment.
  68.  
  69.   The Environment Manager stores two types of named objects: strings and ports.
  70. The names of these two types may not overlap, and each type  must  be  set  and
  71. retrieved  by the appropriately typed primitives.  Sets of variables (called an
  72. environment) are accessible through a specific server port. There  may  be  one
  73. read/write and one read-only port to the same environment.
  74.  
  75.   Environments  are  passed  to  child  tasks  in  one  of two ways. Either the
  76. parent's environment_port is  passed  to  the  child  in  which  case  the  two
  77. processes share the same environment with both having equal write access to all
  78. variables; or the parent clones his environment and passes a copy of it to  the
  79. child. In the latter case the two environments are then completely disjoint. It
  80. is also possible to create a new empty (or default) environment.
  81.  
  82.   It is also possible for one task to use more than one environment.   In  this
  83. way a task could have access to a widely-shared "global" environment as well as
  84. its own local environment.
  85.  
  86. 2. Types
  87.   The following types are defined as smallish fixed length strings in order  to
  88. make the passing of them as in-line message data efficient.
  89.  
  90.   The following types can be included in C programs from <servers/emdefs.h>.
  91.   #define env_name_size  (80)
  92.   #define env_val_size   (256)
  93.  
  94.   typedef char env_name_t[env_name_size];   /* environment variable name */
  95.   typedef char env_str_val_t[env_val_size]; /* string env variable value */
  96.  
  97.   typedef env_name_t     *env_name_list;  /* list of names */
  98.   typedef env_str_val_t  *env_str_list;   /* list of string values */
  99.  
  100.  
  101. 3. Primitives
  102.   The following primitives are provided:
  103. env_string
  104.  
  105. #include <servers/env_mgr.h>
  106.  
  107. kern_return_t env_get_string(env_port,env_name,env_val)
  108.     port_t              env_port;
  109.     env_name_t          env_name;
  110.     env_str_val_t       env_val;
  111. kern_return_t env_set_string(env_port,env_name,env_val)
  112.     port_t              env_port;
  113.     env_name_t          env_name;
  114.     env_str_val_t       env_val;
  115. kern_return_t env_del_string(env_port,env_name)
  116.     port_t              env_port;
  117.     env_name_t          env_name;
  118.  
  119. Arguments
  120.  
  121.   env_port        port identifying environment
  122.  
  123.   env_name        name of string to be found | set | deleted
  124.  
  125.   env_val         returned pointing to value of string
  126.  
  127. Description
  128.  
  129.   env_get_string  returns  the  value  of  the  string  variable  with the name
  130. env_name.
  131.  
  132.   env_set_string sets the string variable env_name to env_val;
  133.  
  134.   env_del_string deletes the string variable env_name.
  135.  
  136. Returns
  137.  
  138.   KERN_SUCCESS    operation succeeded
  139.  
  140.   ENV_UNKNOWN_PORT
  141.                   env_port does not reference a known environment
  142.  
  143.   ENV_VAR_NOT_FOUND
  144.                   name does not exist.
  145.  
  146.   ENV_WRONG_VAR_TYPE
  147.                   names exists, but is a port variable
  148.  
  149.   ENV_READ_ONLY   env_port   only   allows  read  access  to  the  environment.
  150.                   (env_set_string, env_del_string)
  151.  
  152. See Also
  153.  
  154.   env_port[3], env_conn[3], env_list[3]
  155. env_port
  156.  
  157. #include <servers/env_mgr.h>
  158.  
  159. kern_return_t env_get_port(env_port,env_name,env_val)
  160.     port_t              env_port;
  161.     env_name_t          env_name;
  162.     port_t              *env_val;
  163. kern_return_t env_set_port(env_port,env_name,env_val)
  164.     port_t              env_port;
  165.     env_name_t          env_name;
  166.     port_t              env_val;
  167. kern_return_t env_del_port(env_port,env_name)
  168.     port_t              env_port;
  169.     env_name_t          env_name;
  170.  
  171. Arguments
  172.  
  173.   env_port        port identifying environment
  174.  
  175.   env_name        name of port to be found | set | deleted
  176.  
  177.   env_val         returned pointing to value of port
  178.  
  179. Description
  180.  
  181.   env_get_port returns the value of the port variable with the name env_name.
  182.  
  183.   env_set_port sets the value of the port variable, env_name to env_val.
  184.  
  185.   env_del_port deletes the port env_name;
  186.  
  187. Returns
  188.  
  189.   KERN_SUCCESS    variable found
  190.  
  191.   ENV_UNKNOWN_PORT
  192.                   ENV_PORT does not reference a known environment
  193.  
  194.   ENV_VAR_NOT_FOUND
  195.                   name does not exist.
  196.  
  197.   ENV_WRONG_VAR_TYPE
  198.                   names exists, but is a string variable
  199.  
  200.   ENV_READ_ONLY   env_port  only  allows  read  access  to  the  environment. (
  201.                   env_set_port and env_del_port)
  202.  
  203. See Also
  204.  
  205.   env_string[3], env_conn[3], env_list[3]
  206. env_list
  207.  
  208. #include <servers/env_mgr.h>
  209.  
  210. kern_return_t env_list_strings(env_port,env_names,name_cnt,
  211.                                env_string_vals,string_cnt)
  212.     port_t         env_port;
  213.     env_name_list *env_names
  214.     int           *name_cnt;
  215.     env_str_list  *env_string_vals;
  216.     int           *string_cnt);
  217. kern_return_t env_list_ports(env_port,env_names,name_cnt,
  218.                                env_port_vals,port_cnt)
  219.     port_t         env_port;
  220.     env_name_list *env_names
  221.     int           *name_cnt;
  222.     port_array_t  *env_port_vals;
  223.     int           *port_cnt);
  224. kern_return_t env_set_stlist(env_port,env_names,name_cntf,
  225.                              env_string_vals,string_cnt)
  226.     port_t         env_port;
  227.     env_name_list  env_names
  228.     int            name_cnt;
  229.     env_str_list   env_string_vals;
  230.     int            string_cnt);
  231. kern_return_t env_set_ptlist(env_port,env_names,name_cnt,
  232.                              env_port_vals,port_cnt)
  233.     port_t         env_port;
  234.     env_name_list  env_names;
  235.     int            name_cnt;
  236.     port_array_t   env_port_vals;
  237.     int            port_cnt);
  238.  
  239. Arguments
  240.  
  241.   env_port        port identifying environment
  242.  
  243.   env_names       pointer to list of names of all string variables
  244.  
  245.   name_cnt        number of names
  246.  
  247.   env_string_vals pointer to values of string variables (for  env_list_strings)
  248.                   list of values of string variables ( for env_set_stlist )
  249.  
  250.   string_cnt      number of string values (equal to name_cnt)
  251.  
  252.   env_port_vals   pointer to values of port variables (for env_list_ports) list
  253.                   of values of port variables (for env_set_ptlist)
  254.  
  255.   port_cnt        number of port values (equal to name_cnt)
  256.  
  257. Description
  258.  
  259.   env_list_string returns a complete list of all the string  variables  in  the
  260. environment specified by env_port. The two arrays env_names and env_string_vals
  261. are returned in newly allocated virtual memory. This memory should be  released
  262. by a call to vm_deallocate once the items are no longer needed.
  263.  
  264.   env_list_ports  returns  a  complete  list  of  all the port variables in the
  265. environment specified by env_port. The two arrays env_names  and  env_port_vals
  266. are  returned in newly allocated virtual memory. This memory should be released
  267. by a call to vm_deallocate once the items are no longer needed.
  268.  
  269.   env_set_stlist sets a number of string  variables  environment  specified  by
  270. env_port.  This  primitive is provided for efficiency and is mainly intended to
  271. be used to set a Mach environment to be the same as the Unix environ area.
  272.  
  273.   env_set_ptlist sets a number  of  port  variables  environment  specified  by
  274. env_port. This primitive is provided for efficiency.
  275.  
  276. Returns
  277.  
  278.   KERN_SUCCESS    operation succeeded
  279.  
  280.   ENV_UNKNOWN_PORT
  281.                   env_port does not reference a known environment
  282.  
  283.   ENV_READ_ONLY   env_port only allows read access to  the  environment  (  for
  284.                   env_set_stlist and env_set_plist).
  285.  
  286.   ENV_WRONG_VAR_TYPE
  287.                   one of the variables was already defined as a  port  variable
  288.                   (for   env_set_stlist)   or  as  as  string  variable  (  for
  289.                   env_set_ptlist).
  290.  
  291. See Also
  292.  
  293.   env_string[3], env_port[3], env_conn[3]
  294. env_conn
  295.  
  296. #include <servers/env_mgr.h>
  297.  
  298. void init_env_mgr(reply_port);
  299.     port_t      reply_port;
  300. kern_return_t env_new_conn(env_port,new_env_port)
  301.     port_t      env_port;
  302.     port_t      *new_env_port)
  303. kern_return_t env_copy_conn(env_port,new_env_port)
  304.     port_t      env_port;
  305.     port_t      *new_env_port)
  306. kern_return_t env_restrict_conn(env_port,new_env_port)
  307.     port_t      env_port;
  308.     port_t      *new_env_port)
  309. kern_return-t env_disconnect(env_port)
  310.     port_t      env_port;
  311.  
  312. Arguments
  313.  
  314.   reply_port      if equal PORT_NULL, a reply port will be allocated, otherwise
  315.                   reply_port  will  be  used  by  the  interface to receive the
  316.                   message replies.
  317.  
  318.   env_port        port identifying environment
  319.  
  320.   new_env_port    returned pointing to value of new port
  321.  
  322. Description
  323.  
  324.   init_env_mgr initializes the user interface to the Environment Manager.  Must
  325. be  called before any of the other primitives are used. However,it is called by
  326. the library initialization program mach_init, so the user does not need to make
  327. this call unless a different value of Reply_port is desired.
  328.  
  329.   env_new_conn create a new, default environment to be handed to a new process.
  330. This could be initialized with public values  such  as  host_name  and  Network
  331. nameserver port.
  332.  
  333.   env_copy_conn makes a complete copy of the environment specified by env_port,
  334. allocates the new_env_port and  returns  it  to  the  caller.  Subquently,  all
  335. requests  on  new_env_port will use the new copy, and requests on env_port will
  336. continue to refer to the original version. Used by parent to pass a copy of its
  337. environment to a child process.
  338.  
  339.   env_restrict_conn  makes a new port to the environment specified by env_port,
  340. through which only reading will be allowed.
  341.  
  342.   env_disconnect informs the environment manager that  this  enviroment  is  no
  343. longer needed.  EnvMgr will deallocate env_port;
  344.  
  345.   Ownership  rights  to all the new environment ports are returned to the user.
  346. Thus when a process that has created and environment  dies,  these  rights  are
  347. returned  to  the  environment  manager  who  will disconnect (and destroy) the
  348. environment.  If a creator process wishes its environment to live on after  its
  349. death,  it must pass the ownership rights a process that will continue to exist
  350. as long as the environment should exist.
  351.  
  352. Returns
  353.  
  354.   KERN_SUCCESS    new_env_port references a new default environment
  355.  
  356.   ENV_NO_MORE_CONN
  357.                   implementation   restriction,  no  more  connections  to  the
  358.                   Environment Manager are available.
  359.  
  360.   ENV_UNKNOWN_PORT
  361.                   env_port does not reference a known environment
  362.  
  363. See Also
  364.  
  365.   env_string[3], env_port[3], env_list[3], mach_init[3]
  366. 4. Integration with Unix environ
  367.   In  order to allow binary compatibility with Unix, the environ area will have
  368. to be maintained and passed on as usual by execve. If execve  also  clones  the
  369. current Mach environment and passes the new port on to the child, then the Mach
  370. environment will have the same copy semantics as the Unix environ.   If  execve
  371. were  to  enter all the variables in environ into the Mach environment then new
  372. programs could get  all  their  variables  from  the  Mach  environment.    The
  373. primitive  env_set_slist  is  provided  to  allow  a  set of environment string
  374. variables to be entered with one message.
  375.  
  376.   If getenv is changed to call get_env_string, after failing to find a variable
  377. in  the  environ  area,  then  old  programs  will  be able to find environment
  378. variables set by new programs in the  Mach  environment.  The  environment_port
  379. will  be  passed  to  a  new  task  as  part  of the few special ports that all
  380. processes know about.
  381.  
  382.   At some point, the shells will have to be changed to use the Mach environment
  383. in  addition  to the environ area.  Existing Unix variables could be entered in
  384. both places while Mach variables would be put in the Mach environment only.
  385. I. Summary of Calls
  386.  
  387.   The following is a summary of the C calls to the  Environment  Manger.    The
  388. page on which the operation is fully described appears within square brackets.
  389.  
  390.  
  391. [2]  kern_return_t env_get_string(env_port,env_name,env_val)
  392.          port_t              env_port;
  393.          env_name_t          env_name;
  394.          env_str_val_t       env_val;
  395.  
  396.  
  397. [2]  kern_return_t env_set_string(env_port,env_name,env_val)
  398.          port_t              env_port;
  399.          env_name_t          env_name;
  400.          env_str_val_t       env_val;
  401.  
  402.  
  403. [2]  kern_return_t env_del_string(env_port,env_name)
  404.          port_t              env_port;
  405.          env_name_t          env_name;
  406.  
  407.  
  408. [3]  kern_return_t env_get_port(env_port,env_name,env_val)
  409.          port_t              env_port;
  410.          env_name_t          env_name;
  411.          port_t              *env_val;
  412.  
  413.  
  414. [3]  kern_return_t env_set_port(env_port,env_name,env_val)
  415.          port_t              env_port;
  416.          env_name_t          env_name;
  417.          port_t              env_val;
  418.  
  419.  
  420. [3]  kern_return_t env_del_port(env_port,env_name)
  421.          port_t              env_port;
  422.          env_name_t          env_name;
  423.  
  424.  
  425. [4]  kern_return_t env_list_strings(env_port,env_names,name_cnt,
  426.                                     env_string_vals,string_cnt)
  427.          port_t         env_port;
  428.          env_name_list *env_names
  429.          int           *name_cnt;
  430.          env_str_list  *env_string_vals;
  431.          int           *string_cnt);
  432.  
  433.  
  434. [4]  kern_return_t env_list_ports(env_port,env_names,name_cnt,
  435.                                     env_port_vals,port_cnt)
  436.          port_t         env_port;
  437.          env_name_list *env_names
  438.          int           *name_cnt;
  439.          port_array_t  *env_port_vals;
  440.          int           *port_cnt);
  441.  
  442.  
  443. [4]  kern_return_t env_set_stlist(env_port,env_names,name_cntf,
  444.                                   env_string_vals,string_cnt)
  445.          port_t         env_port;
  446.          env_name_list  env_names
  447.          int            name_cnt;
  448.          env_str_list   env_string_vals;
  449.          int            string_cnt);
  450.  
  451.  
  452. [4]  kern_return_t env_set_ptlist(env_port,env_names,name_cnt,
  453.                                   env_port_vals,port_cnt)
  454.          port_t         env_port;
  455.          env_name_list  env_names;
  456.          int            name_cnt;
  457.          port_array_t   env_port_vals;
  458.          int            port_cnt);
  459.  
  460.  
  461. [5]  void init_env_mgr(reply_port);
  462.          port_t      reply_port;
  463.  
  464.  
  465. [5]  kern_return_t env_new_conn(env_port,new_env_port)
  466.          port_t      env_port;
  467.          port_t      *new_env_port)
  468.  
  469.  
  470. [5]  kern_return_t env_copy_conn(env_port,new_env_port)
  471.          port_t      env_port;
  472.          port_t      *new_env_port)
  473.  
  474.  
  475. [5]  kern_return_t env_restrict_conn(env_port,new_env_port)
  476.          port_t      env_port;
  477.          port_t      *new_env_port)
  478.  
  479.  
  480. [5]  kern_return-t env_disconnect(env_port)
  481.          port_t      env_port;
  482.                                Table of Contents
  483. 1. Introduction                                                               1
  484. 2. Types                                                                      1
  485. 3. Primitives                                                                 1
  486. 4. Integration with Unix environ                                              6
  487. I. Summary of Calls                                                           7
  488.