.TH REGISTRIES 2.SH NAMEregistries \- access services registry.SH SYNOPSIS.EXinclude "registries.m";registries := load Registries Registries->PATH; init: fn(); Attributes: adt {   attrs: list of (string, string);    get:   fn(a: self ref Attributes, attr: string): string;   set:   fn(a: self ref Attributes, attr, val: string);   new:   fn(attrs: list of (string, string)): ref Attributes;}; Attached: adt {   fd:           ref Sys->FD;  # connection to the service   signerpkhash: string;     # hash of signer's key   localuser:    string;     # user name here   remoteuser:   string;     # user name there}; Service: adt {   addr:    string;          # dial this to connect to the service   attrs:   ref Attributes;  # service description    attach:  fn(s: self ref Service, user: string,               keydir: string): ref Attached;}; Registered: adt {   addr:    string;          # address where registered   reg:     ref Registry;    # registry where registered   fd:      ref Sys->FD;     # file representing registration entry}; Registry: adt {   dir:     string;    new:        fn(dir: string): ref Registry;   connect:    fn(svc: ref Service, user: string, keydir: string):                  ref Registry;   services:   fn(r: self ref Registry):                  (list of ref Service, string);   find:       fn(r: self ref Registry, a: list of (string, string)):                  (list of ref Service, string);   register:   fn(r: self ref Registry, addr: string,                  attrs: ref Attributes, persist: int):                  (ref Registered, string);   unregister: fn(r: self ref Registry, addr: string): string;};.EE.SH DESCRIPTION.B Registrieshelps access and update the contents of one or more.I registry (4)servers.Each registry lists services, each described by a set of attribute/value pairs.The attributes need not identify the service uniquely..PP.B Initmust be called before any other function in the module..PP.B Attributesrepresents a set of attribute/value pairs;a given attribute name cannot appear more than once.It provides the following members and operations:.TF attrs.PD.TP.B attrsThe current value of the set, as a list of.BI ( attr , value )tuples..TP.BI Attributes.new( attrs )Return a new.B Attributesvalue given.IR attrs ,a list of.BI ( attr , value )tuples..TP.IB a .get( attr )Return the value of.I attrin attribute set.IR a ..TP.IB a .set( attr\fB,\fP\ value )Set the.I valueof.I attrin attribute set.IR a ..PPA.B Servicevalue represents a service registered in some registry.It has the following members and operations:.TF attrs.PD.TP.B addrA string that represents where the service can be reached: it is often a.IR sys-dial (2)address string, but might be a name in the name space; the interpretation is internal to.BR Registries ..TP.B attrsThe service's attributes (complete service description)..TP.IB svc .attach( user , keydir )Attempts to attach to the service.IR svc ,and if successful returns an.B Attachedvalue to represent the connection;otherwise returns nil and sets the system error string..I Useris the local name of the user making the connection; if nil, the contents of.B /dev/userare used by default..I Keydiris the name of a directory containing the.IR user 'scertified keys for authentication; if nil, the default is.BI /usr/ user /keyring.If an error occurs, the return value is nil and the system error string contains a diagnostic.Not all services demand authentication, and either or both values can be nil toselect suitable defaults.If authentication is done, the certified data determines the remote identity, not.IR user ,which is used only to help find a suitable set of keys and has no effect on security..PP.B Attachedholds data about an active connection to a particular service.(There can be several distinct connections to the same.BR Service .)It provides the following members:.TF attrs.PD.TP.B fdA file descriptor that can be read and written to exchange data with the service.The meaning of the data depends on the service (eg, it might be a Styx connectionor a SOAP implementation).Typically an attribute of the service description hints at the protocol..TP.B signerpkhashA hexadecimal string giving the SHA-1 hash of the key of the signer used formutual authentication (ie, its thumbprint); if no authentication was needed ordid not use public key methods, it is nil..TP.B localuserIf authentication was required, the name used as the local name for authentication;otherwise nil..TP.B remoteuserIf authentication was required, the remote identity for this connection; otherwise nil..PPA service provider registers using one of the.B Registryfunctions listed below.An active registration is represented by a value of type.BR Registered :.TF attrs.PD.TP.B addrLocation of service, as registered..TP.B regThe registry that registered the service..TP.B fdFile descriptor open for on the service file in.IR registry (4)that holds the service description.Unless the service has a non-zero.B persistattribute, the service registration will be removed when this file is closed(eg, when this.B Registrationvalue is freed by the garbage collector if there is no other copy of.BR fd ).The file can be written as described in.IR registry (4)to change the some or all of current set of attributes and/or valuesin the service description..PPA.B Registryrepresents a connection to a single.IR registry (4)instance.It provides the following members and operations:.TF attrs.PD.TP.B dirLocation of the registry in the name space..TP.BI Registry.new( dir )Return a new.B Registryvalue for the registry located at.I dirin the name space; if.I diris nil, the default is.BR /mnt/registry ..TP.BI Registry.connect( svc\fB,\fP\ user\fB,\fP\ keydir )Connect to the registry at the location determined by the service description.IR svc ;if.I svcis nil, the default is to try.IR sys-dial (2)to.BR net!$registry!registry ,the symbolic name of the default registry for the current host.(The registry might or might not be local.)Attributes of.I svcdetermine the method used to connect to the registry and whether authentication is required..I Userand.I keydirprovide user name and certificate directory (see.IR getauthinfo (8))if authentication is required; either or both can be nil to select the defaults for the given authentication method.On successful connection,.B connectreturns a.B Registryvalue that can subsequently be used to access that registry and its services.It returns nil on an error and sets the system error string..TP.IB reg ".services()"Returns a tuple.BI ( svcs , err )where.I svcsis a list of.B Servicevalues, one for each service registered by.I regat time of asking.If no services are registered, both values are nil.If an error occurred,.I svcsis nil but.I erris a diagnostic string..TP.IB reg .find( attrs )Return a tuple.BI ( svcs , err )where.I svcsis a list of.B Servicevalues, one for each service registered by.I regthat (at time of asking) matched all of the attribute/value pairs in.IR attrs .A value of.B \&"*"matches any value.If no services matched, both values are nil.If an error occurred,.I svcsis nil but.I erris a diagnostic string..TP.IB reg .register( addr\fB,\fP\ attrs\fB,\fP\ persist )Attempts to register with.I rega service named.I addrand the given attributes.IR attrs ,and returns a tuple.BI ( r , err )where.I ris a non-nil.B Registrationvalue for the entry if successful, and.I erris a diagnostic otherwise..I Persistis non-zero if the service registration should survive the.B Registrationvalue (connection); normally it is zero and the registry entry vanishes whenthe service frees the.B Registrationvalue..TP.IB reg .unregister( addr )Attempt to remove the registration entry at.I regfor the service named.IR addr .Only the service owner can do so.Returns nil on success and a diagnostic otherwise..SH SEE ALSO.IR attrdb (2),.IR registry (4),.IR svc (8)