intro(3ncs)intro(3ncs)Nameintro - 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 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
· Interface to the Location Broker
· Fault Management
· Program Management
· Interface to the Remote Procedure Call Runtime Library
· Remote Remote Procedure Call Interface
· Operations on Socket Addresses
· Operations on Universal Unique Identifiers
Error Text Database Operations
The error text database operations use the and library routines to con‐
vert 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 sta‐
tus_$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 con‐
dition.
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
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 fol‐
lows:
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 sta‐
tus_$ok, the routine that supplied the status was suc‐
cessful.
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 Loca‐
tion 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 rou‐
tines. Specifies that a lookup is to start search‐
ing 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 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 associ‐
ated.
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 Bro‐
ker (GLB) databases. A value
of lb_$server_flag_local speci‐
fies 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 Bro‐
ker databases in which an entry is to be regis‐
tered. 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 inte‐
ger:
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 sim‐
ply 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 han‐
dlers have completed. It releases any resources still held by the pro‐
gram, 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 sig‐
nals.
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 inte‐
ger:
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 descrip‐
tion 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 communi‐
cations 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 proce‐
dures.
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 inter‐
face, and the number of operations in the inter‐
face.
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 defini‐
tion for rpc_$shut_check_fn_t illustrates the pro‐
totype for this function:
typedef boolean (*rpc_$shut_check_fn_t) (
handle_t h,
status_$t *st)
The handle argument can be used to determine infor‐
mation 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 sta‐
tus_$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 speci‐
fiers.
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, includ‐
ing 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 operate
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 com‐
pared.
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 fam‐
ily. The Constants section lists values for this
type.
socket_$addr_list_t An array of socket addresses in socket_$addr_t for‐
mat.
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 spec‐
ifying 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 con‐
tains 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 sta‐
tus_$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 com‐
pletion 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 fol‐
lows:
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 encoun‐
tered 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 time‐
stamp, ff is the address family, and h1 ... h7 are the 7 bytes
of host identifier. Each character in these fields is a hexa‐
decimal 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 cre‐
ated. The format of this field depends on the address
family.
Example
The following routine returns as the UUID corresponding to the charac‐
ter-string representation in
uuid_$decode (foo_uuid_rep, &foo_uuid, &status);
intro(3ncs)
