intro man page on Ultrix

Man page or keyword search:  
man Server   3690 pages
apropos Keyword Search (all sections)
Output format
Ultrix logo
[printable version]

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 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)
[top]

List of man pages available for Ultrix

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
...................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net