Query: intro
OS: ultrix
Section: 3ncs
Format: Original Unix Latex Style Formatted with HTML and a Horizontal Scroll Bar
intro(3ncs) intro(3ncs) Name intro - introduction to the Network Computing System's (NCS) library routines Description This section describes the NCS library routines. The Title, Name, and See Also sections of the NCS reference pages do not contain the dol- lar ($) sign in the command names and library routines. The actual NCS commands and library routines do contain the dollar ($) sign. The NCS commands and library routines are as follows: o Error Text Database Operations o Interface to the Location Broker o Fault Management o Program Management o Interface to the Remote Procedure Call Runtime Library o Remote Remote Procedure Call Interface o Operations on Socket Addresses o Operations on Universal Unique Identifiers Error Text Database Operations The error text database operations use the and library routines to convert status codes into textual error messages. The runtime library reports operational problems back to the application following a call by setting the `all' field of the status_$t structure. A value of status_$ok indicates that no errors were detected. Any other value implies that a problem occurred. The status_$t structure and the rou- tines can be used to display a textual representation of the error condition. Data Types This section describes the data types used in routines. The routines take as input a status code in status_$t format. status_$t A status code. Most of the NCS routines supply their completion status in this format. The status_$t type is defined as a struc- ture containing a long integer: struct status_$t { long all; } However, the routines can also use status_$t as a set of bit fields. To access the fields in a returned status code, you can assign the value of the status code to a union defined as follows: typedef union { struct { unsigned fail : 1, subsys : 7, modc : 8; short code; } s; long all; } status_u; all All 32 bits in the status code. If all is equal to status_$ok, the routine that supplied the status was successful. fail If this bit is set, the error was not within the scope of the module invoked, but occurred within a lower-level module. subsys This indicates the subsystem that encountered the error. modc This indicates the module that encountered the error. code This is a signed number that identifies the type of error that occurred. Interface To The Location Broker The library routines implement the programmatic interface to the Location Broker Client Agent. The file defines this interface. External Variables This section describes the external variable used in routines. uuid_$nil An external uuid_$t variable that is preassigned the value of the nil UUID. Do not change the value of this variable. Constants This section describes constants used in routines. lb_$default_lookup_handle Used as an input in Location Broker lookup routines. Specifies that a lookup is to start searching at the beginning of the database. lb_$server_flag_local Used in the flags field of an lb_$entry_t variable. Specifies that an entry is to be registered only in the Local Location Broker (LLB) database. See the description of lb_$server_flag_t in the Data Types section. status_$ok A constant used to check status. If a completion status is equal to status_$ok, then the routine that supplied it was successful. Data Types This section describes data types used in routines. lb_$entry_t An identifier for an object, a type, an interface, and the socket address used to access a server exporting the inter- face to the object. The lb_$entry_t type is defined as follows: typedef struct lb_$entry_t lb_$entry_t; struct lb_$entry_t { uuid_$t object; uuid_$t obj_type; uuid_$t obj_interface; lb_$server_flag_t flags; ndr_$char annotation[64]; ndr_$ulong_int saddr_len; socket_$addr_t saddr; }; object A uuid_$t. The UUID for the object. Can be uuid_$nil if no object is associated. obj_type A uuid_$t. The UUID for the type of the object. Can be uuid_$nil if no type is associated. obj_interface A uuid_$t. The UUID for the interface. Can be uuid_$nil if no interface is associated. flags An lb_$server_flag_t. Must be 0 or lb_$server_flag_local. A value of 0 specifies that the entry is to be registered in both the Local Location Broker (LLB) and global Location Broker (GLB) data- bases. A value of lb_$server_flag_local specifies registration only in the LLB database. annotation A 64-character array. User-defined textual annotation. saddr_len A 32-bit integer. The length of the saddr field. saddr A socket_$addr_t. The socket address of the server. lb_$lookup_handle_t A 32-bit integer used to specify the location in the database at which a Location Broker lookup operation will start. lb_$server_flag_t A 32-bit integer used to specify the Location Broker databases in which an entry is to be registered. A value of 0 specifies registration in both the Local Location Broker (LLB) and Global Location Broker (GLB) databases. A value of lb_$server_flag_local specifies registration only in the LLB database. socket_$addr_t A socket address record that uniquely identifies a socket. status_$t A status code. Most of the NCS routines supply a completion code in this format. The status_$t type is defined as a structure containing a long integer: struct status_$t { long all; } However, the system calls can also use status_$t as a set of bit fields. To access the fields in a returned status code, you can assign the value of the status code to a union defined as follows: typedef union { struct { unsigned fail : 1, subsys : 7, modc : 8; short code; } s; long all; } status_u; all All 32 bits in the status code. If all is equal to status_$ok, the system call that supplied the status was successful. fail If this bit is set, the error was not within the scope of the module invoked, but occurred within a lower-level module. subsys This indicates the subsystem that encountered the error. modc This indicates the module that encountered the error. code This is a signed number that identifies the type of error that occurred. uuid_$t A 128-bit value that uniquely identifies an object, type, or interface for all time. Example The following statement looks up information in the GLB database about a matrix multiplication interface: lb_$lookup_interface (&matrix_id, &lookup_handle, max_results, &num_results, &matrix_results, &st); Fault Management The routines allow programs to manage signals, faults, and exceptions by establishing clean-up handlers. A clean-up handler is a piece of code that ensures a program terminates gracefully when it receives a fatal error. A clean-up handler begins with a call, and usually ends with a call to or though it can also simply continue back into the program after the clean-up code. A clean-up handler is not entered until all fault handlers established for a fault have returned. If there is more than one established clean-up handler for a program, the most recently established clean-up handler is entered first, followed by the next most recently estab- lished clean-up handler, and so on to the first established clean-up handler if necessary. There is a default clean-up handler invoked after all user-defined handlers have completed. It releases any resources still held by the program, before returning control to the process that invoked it. Constants pfm_$init_signal_handlers A constant used as the flags parameter to causing C signals to be intercepted and converted to PFM signals. Data Types This section describes the data typed used in pfm_$ routines. pfm_$cleanup_rec A record type for passing process context among clean-up handler routines. It is an opaque data type. status_$t A status code. Most of the NCS routines supply a completion code in this format. The status_$t type is defined as a structure containing a long integer: struct status_$t { long all; } However, the system calls can also use status_$t as a set of bit fields. To access the fields in a returned status code, you can assign the value of the status code to a union defined as follows: typedef union { struct { unsigned fail : 1, subsys : 7, modc : 8; short code; } s; long all; } status_u; all All 32 bits in the status code. If all is equal to status_$ok, the system call that supplied the status was successful. fail If this bit is set, the error was not within the scope of the module invoked, but occurred within a lower-level module. subsys This indicates the subsystem that encountered the error. modc This indicates the module that encountered the error. code This is a signed number that identifies the type of error that occurred. Program Management The NCS software products contain a portable version of the routine. The include file for the PFM interface (see the Syntax section of the reference pages) contains a declaration for this routine. Interface To The Remote Procedure Call Runtime Library The library routines implement the NCS Remote Procedure Call (RPC) mechanism. The interface is defined by the file Most of the routines can be used only by clients or only by servers. This aspect of their usage is specified at the beginning of each rou- tine description, in the Name section. External Variables This section describes the external variable used in rpc_$ routines. uuid_$nil An external uuid_$t variable that is preassigned the value of the nil UUID. Do not change the value of this variable. Constants This section describes constants used in rpc_$ routines. rpc_$mod A module code indicating the RPC module. status_$ok A constant used to check status. If a completion status is equal to status_$ok, then the routine that supplied it was successful. See the description of the status_$t type. rpc_$unbound_port A port number indicating to the RPC runtime library that no port is specified. Identical to socket_$unspec_port. The following 16-bit-integer constants are used to specify the communications protocol address families in socket_$addr_t structures. Note that several of the rpc_$ and socket_$ calls use the 32-bit-integer equivalents of these values. socket_$unspec Address family is unspecified. socket_$internet Internet Protocols (IP). Data Types This section describes data types used in rpc_$ routines. handle_t An RPC handle. rpc_$epv_t An entry point vector (EPV). An array of rpc_$server_stub_t, pointers to server stub procedures. rpc_$generic_epv_t An entry point vector (EPV). An array of rpc_$generic_server_stub_t, pointers to generic server stub procedures. rpc_$if_spec_t An RPC interface specifier. This opaque data type contains information about an interface, including its UUID, the current version number, any well-known ports used by servers that export the interface, and the number of operations in the interface. rpc_$mgr_epv_t An entry point vector (EPV). An array of pointers to manager procedures. rpc_$shut_check_fn_t A pointer to a function. If a server supplies this function pointer to rpc_$allow_remote_shutdown, the function will be called when a remote shutdown request arrives, and if the function returns true, the shutdown is allowed. The fol- lowing C definition for rpc_$shut_check_fn_t illustrates the prototype for this function: typedef boolean (*rpc_$shut_check_fn_t) ( handle_t h, status_$t *st) The handle argument can be used to determine information about the remote caller. socket_$addr_t A socket address record that uniquely identifies a socket. status_$t A status code. Most of the NCS system calls supply their completion status in this format. The status_$t type is defined as a structure containing a long integer: struct status_$t { long all; } However, the system calls can also use status_$t as a set of bit fields. To access the fields in a returned status code, you can assign the value of the status code to a union defined as follows: typedef union { struct { unsigned fail : 1, subsys : 7, modc : 8; short code; } s; long all; } status_u; all All 32 bits in the status code. If all is equal to status_$ok, the system call that supplied the status was successful. fail If this bit is set, the error was not within the scope of the module invoked, but occurred within a lower-level module. subsys This indicates the subsystem that encountered the error. modc This indicates the module that encountered the error. code This is a signed number that identifies the type of error that occurred. uuid_$t A 128-bit value that uniquely identifies an object, type, or interface for all time. The following statement allocates a handle that identifies the Acme company's payroll database object: h = rpc_$alloc_handle (&acme_pay_id, socket_$internet, &st); Remote Remote Procedure Call Interface The library routines enable a client to request information about a server or to shut down a server. The interface is defined by the file Constants This section describes constants used in rrpc_$ calls. The rrpc_$sv constants are indices for elements in an rrpc_$stat_vec_t array. Each element is a 32-bit integer representing a statistic about a server. The following list describes the statistic indexed by each rrpc_$sv constant: rrpc_$sv_calls_in The number of calls processed by the server. rrpc_$sv_rcvd The number of packets received by the server. rrpc_$sv_sent The number of packets sent by the server. rrpc_$sv_calls_out The number of calls made by the server. rrpc_$sv_frag_resends The number of fragments sent by the server that duplicated previous sends. rrpc_$sv_dup_frags_rcvd The number of duplicate fragments received by the server. status_$ok A constant used to check status. If a completion status is equal to status_$ok, then the system call that supplied it was successful. Data Types This section describes data types used in rpc_$ routines. handle_t An RPC handle. rrpc_$interface_vec_t An array of rpc_$if_spec_t, RPC interface specifiers. rrpc_$stat_vec_t An array of 32-bit integers, indexed by rrpc_$sv constants, representing statistics about a server. rpc_$if_spec_t An RPC interface specifier. An opaque data type containing information about an interface, including the UUID, the version number, the number of operations in the interface, and any well-known ports used by servers that export the interface, and any well-known ports used by servers that export the interface. Applications may need to access two members of rpc_$if_spec_t: id A uuid_$t indicating the interface UUID. vers An unsigned 32-bit integer indicating the interface version. Operations on Socket Addresses The library routines manipulate socket addresses. Unlike the routines that operating systems such as BSD UNIX provide, the routines oper- ate on addresses of any protocol family. The file defines the interface. Constants This section describes constants used in socket_$ routines. The socket_$eq constants are flags indicating the fields to be compared in a socket_$equal call. socket_$eq_hostid Indicates that the host IDs are to be compared. socket_$eq_netaddr Indicates that the network addresses are to be compared. socket_$eq_port Indicates that the port numbers are to be compared. socket_$eq_network Indicates that the network IDs are to be compared. socket_$unspec_port A port number indicating to the RPC runtime library that no port is specified. The following 16-bit-integer constants are values for the socket_$addr_family_t type, used to specify the address family in a socket_$addr_t structure. Note that several of the rpc_$ and socket_$ routines use the 32-bit-integer equivalents of these values. socket_$unspec Address family is unspecified. socket_$internet Internet Protocols (IP). status_$ok A constant used to check status. If a completion status is equal to status_$ok, then the system call that supplied it was successful. Data Types This section describes data types used in socket_$ routines. socket_$addr_family_t An enumerated type for specifying an address family. The Constants section lists values for this type. socket_$addr_list_t An array of socket addresses in socket_$addr_t format. socket_$addr_t A structure that uniquely identifies a socket address. This structure consists of a socket_$addr_family_t specifying an address family and 14 bytes specifying a socket address. socket_$host_id_t A structure that uniquely identifies a host. This structure consists of a socket_$addr_family_t specifying an address family and 12 bytes specifying a host. socket_$len_list_t An array of unsigned 32-bit integers, the lengths of socket addresses in a socket_$addr_list_t. socket_$local_sockaddr_t An array of 50 characters, used to store a socket address in a format native to the local host. socket_$net_addr_t A structure that uniquely identifies a network address. This structure consists of a socket_$addr_family_t specifying an address family and 12 bytes specifying a network address. It contains both a host ID and a network ID. socket_$string_t An array of 100 characters, used to store the string representation of an address family or a socket address. The string representation of an address family is a textual name such as dds, ip, or unspec. The string representation of a socket address has the format family:host[port], where family is the textual name of an address family, host is either a textual host name or a numeric host ID preceded by a #, and port is a port number. status_$t A status code. Most of the NCS system calls supply their completion status in this format. The status_$t type is defined as a structure containing a long integer: struct status_$t { long all; } However, the system calls can also use status_$t as a set of bit fields. To access the fields in a returned status code, you can assign the value of the status code to a union defined as follows: typedef union { struct { unsigned fail : 1, subsys : 7, modc : 8; short code; } s; long all; } status_u; all All 32 bits in the status code. If all is equal to status_$ok, the system call that supplied the status was successful. fail If this bit is set, the error was not within the scope of the module invoked, but occurred within a lower-level module. subsys This indicates the subsystem that encountered the error. modc This indicates the module that encountered the error. code This is a signed number that identifies the type of error that occurred. Operations On Universal Unique Identifiers The library routines operate on UUIDs (Universal Unique Identifiers). The interface is defined by the file External Variables This section describes external variables used in uuid_$ routines. uuid_$nil An external uuid_$t variable that is preassigned the value of the nil UUID. Do not change the value of this variable. Data Types This section describes data types used in uuid_$ routines. status_$t A status code. Most of the NCS system calls supply their completion status in this format. The status_$t type is defined as a structure containing a long integer: struct status_$t { long all; } However, the system calls can also use status_$t as a set of bit fields. To access the fields in a returned status code, you can assign the value of the status code to a union defined as follows: typedef union { struct { unsigned fail : 1, subsys : 7, modc : 8; short code; } s; long all; } status_u; all All 32 bits in the status code. If all is equal to status_$ok, the system call that supplied the status was successful. fail If this bit is set, the error was not within the scope of the module invoked, but occurred within a lower-level module. subsys This indicates the subsystem that encountered the error. modc This indicates the module that encountered the error. code This is a signed number that identifies the type of error that occurred. uuid_$string_t A string of 37 characters (including a null terminator) that is an ASCII representation of a UUID. The format is ccccccccc- ccc.ff.h1.h2.h3.h4.h5.h6.h7, where cccccccccccc is the timestamp, ff is the address family, and h1 ... h7 are the 7 bytes of host identifier. Each character in these fields is a hexadecimal digit. uuid_$t A 128-bit value that uniquely identifies an object, type, or interface for all time. The uuid_$t type is defined as follows: typedef struct uuid_$t { unsigned long time_high; unsigned short time_low; unsigned short reserved; unsigned char family; unsigned char (host)[7]; } uuid_$t; time_high The high 32 bits of a 48-bit unsigned time value which is the number of 4-microsecond intervals that have passed between 1 January 1980 00:00 GMT and the time of UUID creation. time_low The low 16 bits of the 48-bit time value. reserved 16 bits of reserved space. family 8 bits identifying an address family. host 7 bytes identifying the host on which the UUID was created. The format of this field depends on the address family. Example The following routine returns as the UUID corresponding to the character-string representation in uuid_$decode (foo_uuid_rep, &foo_uuid, &status); intro(3ncs)