intro.3ncs

<B>Digital的Unix操作系统VAX 4.2源码</B>

.TP 20
\fBrpc_$shut_check_fn_t\fR
A pointer to a function.
If a server supplies this function pointer to \fBrpc_$allow_remote_shutdown\fR,
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 \fBrpc_$shut_check_fn_t\fR
illustrates the prototype for this function:
.EX
typedef boolean (*rpc_$shut_check_fn_t) (
    handle_t h,
    status_$t *st)
.EE
The handle argument can be used to determine information about the remote caller.
.TP 20
\fBsocket_$addr_t\fR
A socket address record that uniquely identifies a socket.
.\".if t the \fBsocket_$intro\fR section of Chapter \n(sO
.\".if n \fBsocket_$intro\fR
.TP 20
\fBstatus_$t\fR
A status code.
Most of the NCS system calls supply their completion status in this format.
The \fBstatus_$t\fR type is defined as a structure containing a long integer:
.EX
struct status_$t {
    long all;
    }
.EE
However, the system calls can also use \fBstatus_$t\fR 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:
.EX
typedef union {
    struct {
        unsigned fail : 1,
                 subsys : 7,
                 modc : 8;
        short    code;
    } s;
    long all;
} status_u;
.EE
.RS
.TP 20
\fBall\fR
All 32 bits in the status code.
If \fBall\fR is equal to \fBstatus_$ok\fR,
the system call that supplied the status was successful.
.TP 20
\fBfail\fR
If this bit is set,
the error was not within the scope of the module invoked,
but occurred within a lower-level module.
.TP 20
\fBsubsys\fR
This indicates the subsystem that encountered the error.
.br
.ne 3
.TP 20
\fBmodc\fR
This indicates the module that encountered the error.
.TP 20
\fBcode\fR
This is a signed number that identifies the
type of error that occurred.
.RE
.TP 20
\fBuuid_$t\fR
A 128-bit value that uniquely identifies
an object, type, or interface for all time.
.\".if t the \fBuuid_$intro\fR section of Chapter \n(uU
.\".if n \fBuuid_$intro\fR
.PP
The following statement allocates a handle that identifies the Acme 
company's payroll database object:
.EX
h = rpc_$alloc_handle (&acme_pay_id, socket_$internet, &st);
.EE
.SS Remote Remote Procedure Call Interface 
The 
.PN rrpc_$
library routines enable a client to request information about a server or
to shut down a server.
.PP
The
.PN rrpc_
interface is defined by the file
.PN /usr/include/idl/rrpc.idl .
.PP
.B Constants
.br
This section describes constants used in \fBrrpc_$\fR calls.
.PP
The \fBrrpc_$sv\fR constants are indices for elements in
an \fBrrpc_$stat_vec_t\fR array.
Each element is a 32-bit integer representing a statistic about a server.
The following list describes the statistic indexed by each \fBrrpc_$sv\fR constant:
.RS
.TP 20
\fBrrpc_$sv_calls_in\fR
The number of calls processed by the server.
.TP 20
\fBrrpc_$sv_rcvd\fR
The number of packets received by the server.
.TP 20
\fBrrpc_$sv_sent\fR
The number of packets sent by the server.
.TP 20
\fBrrpc_$sv_calls_out\fR
The number of calls made by the server.
.TP 20
\fBrrpc_$sv_frag_resends\fR
The number of fragments sent by the server that duplicated previous sends.
.TP 20
\fBrrpc_$sv_dup_frags_rcvd\fR
The number of duplicate fragments received by the server.
.RE
.TP 20
\fBstatus_$ok\fR
A constant used to check status.
If a completion status
is equal to \fBstatus_$ok\fR,
then the system call that supplied it was successful.
.PP
.B Data Types
.br
This section describes data types used in \fBrpc_$\fR routines.
.TP 20
\fBhandle_t\fR
An RPC handle.
.TP 20
\fBrrpc_$interface_vec_t\fR
An array of \fBrpc_$if_spec_t\fR,
RPC interface specifiers.
.TP 20
\fBrrpc_$stat_vec_t\fR
An array of 32-bit integers, indexed by
.B rrpc_$sv
constants, representing statistics about a server. 
.TP 20
\fBrpc_$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
\fBrpc_$if_spec_t\fP:
.RS
.TP 7
\fBid\fP
A \fBuuid_$t\fP indicating the interface UUID.
.TP 7 
\fBvers\fP
An unsigned 32-bit integer indicating the interface version.
.RE
.SS Operations on Socket Addresses 
The 
.PN socket_$
library routines manipulate socket addresses.
Unlike the routines that operating systems such as BSD UNIX provide,
the 
.PN socket_$
routines operate on addresses of any protocol family.
.PP
The file 
.PN /usr/include/idl/socket.idl
defines the
.PN socket_
interface.
.PP
.B Constants
.br
This section describes constants used in \fBsocket_$\fR routines.
.PP
The \fBsocket_$eq\fR constants
are flags indicating the fields to be compared in a \fBsocket_$equal\fR call.
.RS
.TP 20
\fBsocket_$eq_hostid\fR
Indicates that the host IDs are to be compared.
.TP 20
\fBsocket_$eq_netaddr\fR
Indicates that the network addresses are to be compared.
.TP 20
\fBsocket_$eq_port\fR
Indicates that the port numbers are to be compared.
.TP 20
\fBsocket_$eq_network\fR
Indicates that the network IDs are to be compared.
.RE
.TP 20
\fBsocket_$unspec_port\fR\" 0
A port number indicating
to the RPC runtime library that no port is specified.
.PP
The following 16-bit-integer constants are
values for the \fBsocket_$addr_family_t\fR type,
used to specify the address family in a \fBsocket_$addr_t\fR structure.
Note that several of the \fBrpc_$\fR and \fBsocket_$\fR routines
use the 32-bit-integer equivalents of these values.
.RS
.TP 20
\fBsocket_$unspec\fR\" 0
Address family is unspecified. 
.TP 20
\fBsocket_$internet\fR\" 2
Internet Protocols (IP).
.RE
.TP 20
\fBstatus_$ok\fR
A constant used to check status.
If a completion status
is equal to \fBstatus_$ok\fR,
then the system call that supplied it was successful.
.PP
.B Data Types
.br
This section describes data types used in \fBsocket_$\fR routines.
.TP 20
\fBsocket_$addr_family_t\fR
An enumerated type for specifying an address family.
The Constants
section lists values for this type.
.ig
	.RS
	.TP 20
	\fBsocket_$unspec\fR
	Unspecified protocol.
	.TP 20
	\fBsocket_$unix\fR
	Local to host (UNIX pipes, portals).
	.TP 20
	\fBsocket_$internet\fR
	Internetwork protocols (TCP, UDP).
	.TP 20
	\fBsocket_$implink\fR
	ARPANET Interface Message Processor (IMP) addresses.
	.TP 20
	\fBsocket_$pup\fR
	XEROX P.A.R.C. Universal Packet (PUP) protocols (BSP).
	.TP 20
	\fBsocket_$chaos\fR
	Massachusetts Institute of Technology (MIT) CHAOS protocols.
	.TP 20
	\fBsocket_$ns\fR
	XEROX Network Systems (XNS) protocols.
	.TP 20
	\fBsocket_$nbs\fR
	National Bureau of Standards (NBS) protocols.
	.TP 20
	\fBsocket_$ecma\fR
	European Computer Manufacturers Association (ECMA).
	.TP 20
	\fBsocket_$datakit\fR
	Datakit protocols.
	.TP 20
	\fBsocket_$ccitt\fR
	International Telegraph and Telephone Consultative Committee
        (CCITT) protocols (X.25, ...).
	.TP 20
	\fBsocket_$sna\fR
	IBM Systems Network Architecture (SNA) protocols.
	.TP 20
	\fBsocket_$unspec2\fR
	Unspecified protocol.
	.TP 20
	\fBsocket_$dds\fR
	Apollo Domain/Message (MSG) protocol.
	.RE
..
.TP 20
\fBsocket_$addr_list_t\fR
An array of socket addresses in \fBsocket_$addr_t\fR format.
.br
.ne 3
.TP 20
\fBsocket_$addr_t\fR
A structure that uniquely identifies a socket address.
This structure consists of
a \fBsocket_$addr_family_t\fR specifying an address family
and 14 bytes specifying a socket address.
.TP 20
\fBsocket_$host_id_t\fR
A structure that uniquely identifies a host.
This structure consists of
a \fBsocket_$addr_family_t\fR specifying an address family
and 12 bytes specifying a host.
.TP 20
\fBsocket_$len_list_t\fR
An array of unsigned 32-bit integers,
the lengths of socket addresses in a \fBsocket_$addr_list_t\fR.
.TP 20
\fBsocket_$local_sockaddr_t\fR
An array of 50 characters,
used to store a socket address in a format native to the local host.
.TP 20
\fBsocket_$net_addr_t\fR
A structure that uniquely identifies a network address.
This structure consists of
a \fBsocket_$addr_family_t\fR specifying an address family
and 12 bytes specifying a network address.
It contains both a host ID and a network ID.
.TP 20
\fBsocket_$string_t\fR
An array of 100 characters,
used to store the string representation of an address family or a socket address.
.if t .sp .5
The string representation of an address family is a textual name
such as \fBdds\fR, \fBip\fR, or \fBunspec\fR.
.if t .sp .5
The string representation of a socket address has the format
\fIfamily\fB:\fIhost\fB\|[\|\fIport\fB\|]\|\fR, where
\fIfamily\fR is the textual name of an address family,
\fIhost\fR is either
a textual host name
or a numeric host ID preceded by a \fB#\fR,
and \fIport\fR is a port number.
.TP 20
\fBstatus_$t\fR
A status code.
Most of the NCS system calls supply their completion status in this format.
The \fBstatus_$t\fR type is defined as a structure containing a long integer:
.EX
struct status_$t {
    long all;
    }
.EE
However, the system calls can also use \fBstatus_$t\fR 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:
.EX
typedef union {
    struct {
        unsigned fail : 1,
                 subsys : 7,
                 modc : 8;
        short    code;
    } s;
    long all;
} status_u;
.EE
.RS
.TP 20
\fBall\fR
All 32 bits in the status code.
If \fBall\fR is equal to \fBstatus_$ok\fR,
the system call that supplied the status was successful.
.br
.ne 3
.TP 20
\fBfail\fR
If this bit is set,
the error was not within the scope of the module invoked,
but occurred within a lower-level module.
.TP 20
\fBsubsys\fR
This indicates the subsystem that encountered the error.
.br
.ne 3
.TP 20
\fBmodc\fR
This indicates the module that encountered the error.
.TP 20
\fBcode\fR
This is a signed number that identifies the
type of error that occurred.
.RE
.SS Operations On Universal Unique Identifiers 
The 
.PN uuid_$
library routines operate on UUIDs (Universal Unique Identifiers).
.PP
The 
.PN uuid_
interface is defined by the file
.PN /usr/include/idl/uuid.idl .
.PP
.B External Variables
.br
This section describes external variables used in \fBuuid_$\fR routines.
.TP
\fBuuid_$nil\fR
An external \fBuuid_$t\fR variable
that is preassigned the value of the nil UUID.
Do not change the value of this variable.
.PP
.B Data Types
.br
This section describes data types used in \fBuuid_$\fR routines.
.TP
\fBstatus_$t\fR
A status code.  Most of the NCS system calls supply their completion
status in this format.  The \fBstatus_$t\fR type is defined as a
structure containing a long integer:
.EX
struct status_$t {
    long all;
    }
.EE
However, the system calls can also use \fBstatus_$t\fR 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:
.EX
typedef union {
    struct {
        unsigned fail : 1,
                 subsys : 7,
                 modc : 8;
        short    code;
    } s;
    long all;
} status_u;
.EE
.RS
.TP 20
\fBall\fR
All 32 bits in the status code.
If \fBall\fR is equal to \fBstatus_$ok\fR,
the system call that supplied the status was successful.
.TP 20
\fBfail\fR
If this bit is set,
the error was not within the scope of the module invoked,
but occurred within a lower-level module.
.TP 20
\fBsubsys\fR
This indicates the subsystem that encountered the error.
.TP 20
\fBmodc\fR
This indicates the module that encountered the error.
.TP 20
\fBcode\fR
This is a signed number that identifies the
type of error that occurred.
.RE
.TP
\fBuuid_$string_t\fR
A string of 37 characters (including a null terminator)
that is an ASCII representation of a UUID.
The format is
\fIcccccccccccc\fB\|.\|\fIff\fB\|.\|\fIh1\fB\|.\|\fIh2\fB\|.\|\fIh3\fB\|.\|\fIh4\fB\|.\|\fIh5\fB\|.\|\fIh6\fB\|.\|\fIh7\fR,
where
\fIcccccccccccc\fR is the timestamp,
\fIff\fR is the address family,
and
\fIh1\fR ... \fIh7\fR are the 7 bytes of host identifier.
Each character in these fields is a hexadecimal digit.
.TP
\fBuuid_$t\fR
A 128-bit value that uniquely identifies
an object, type, or interface for all time.
The \fBuuid_$t\fR type is defined as follows:
.EX
typedef struct uuid_$t {
    unsigned long time_high;
    unsigned short time_low;
    unsigned short reserved;
    unsigned char family;
    unsigned char (host)[7];
} uuid_$t;
.EE
.RS
.TP
\fBtime_high\fR
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.
.TP
\fBtime_low\fR
The low 16 bits of the 48-bit time value.
.TP
\fBreserved\fR
16 bits of reserved space.
.TP
\fBfamily\fR
8 bits identifying an address family.\" corresponds to field of socket_$addr_t?
.TP
\fBhost\fR
7 bytes identifying the host on which the UUID was created.
The format of this field depends on the address family.
.RE
.PP
.B Example
.br
The following routine returns as 
.PN foo_uuid
the UUID corresponding to the character-string representation in 
.PN foo_uuid_rep:
.EX
uuid_$decode (foo_uuid_rep, &foo_uuid, &status);
.EE