Visit The New, Modern Unix Linux Community

Linux and UNIX Man Pages

Test Your Knowledge in Computers #614
Difficulty: Medium
In Python, strings in double quotes work exactly the same way as strings in single quotes.
True or False?
Linux & Unix Commands - Search Man Pages

intro(3ncs) [ultrix man page]

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)

Featured Tech Videos