intro(3ncs)
Name
intro − introduction to the Network Computing System’s (NCS) library routines
Description
This section describes the NCS library routines.
Note
The Title, Name, and See Also sections of the NCS reference pages do not contain the dollar ($) 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:
•Error Text Database Operations (error_$)
•Interface to the Location Broker (lb_$)
•Fault Management (pfm_$)
•Program Management (pgm_$)
•Interface to the Remote Procedure Call Runtime Library (rpc_$)
•Remote Remote Procedure Call Interface (rrpc_$)
•Operations on Socket Addresses (socket_$)
•Operations on Universal Unique Identifiers (uuid_$)
Error Text Database Operations
The error text database operations use the error_$c_get_text and error_$c_text 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 error_$ routines can be used to display a textual representation of the error condition.
Data Types
This section describes the data types used in error_$ routines.
The error_$ 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 structure 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 lb_$ library routines implement the programmatic interface to the Location Broker Client Agent. The file /usr/include/idl/c/glb.h defines this interface.
External Variables
This section describes the external variable used in lb_$ 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 lb_$ 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 lb_$ routines.
lb_$entry_t An identifier for an object, a type, an interface, and the socket address used to access a server exporting the interface 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) databases. 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 pfm_$ 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 pfm_$cleanup call, and usually ends with a call to pfm_$signal or pgm_$exit, 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 established 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 pfm_$init, 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 pgm_$exit routine. The include file for the PFM interface (see the Syntax section of the pfm() reference pages) contains a declaration for this routine.
Interface To The Remote Procedure Call Runtime Library
The rpc_$ library routines implement the NCS Remote Procedure Call (RPC) mechanism.
The rpc_ interface is defined by the file /usr/include/idl/rpc.idl.
Most of the rpc_$ routines can be used only by clients or only by servers. This aspect of their usage is specified at the beginning of each routine 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 following 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 rrpc_$ library routines enable a client to request information about a server or to shut down a server.
The rrpc_ interface is defined by the file /usr/include/idl/rrpc.idl.
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 socket_$ library routines manipulate socket addresses. Unlike the routines that operating systems such as BSD UNIX provide, the socket_$ routines operate on addresses of any protocol family.
The file /usr/include/idl/socket.idl defines the socket_ 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 uuid_$ library routines operate on UUIDs (Universal Unique Identifiers).
The uuid_ interface is defined by the file /usr/include/idl/uuid.idl.
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 cccccccccccc.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 foo_uuid the UUID corresponding to the character-string representation in foo_uuid_rep:
uuid_$decode (foo_uuid_rep, &foo_uuid, &status);