1 DCE HP's Distributed Computing Environment (DCE) for OpenVMS Alpha and OpenVMS I64 provides an important enabling software technology for the development of distributed applications. DCE makes the underlying network architecture transparent to application developers. It consists of a software layer between the operating system/network interface and the distributed application program. It provides a variety of common services needed for development of distributed applications, such as name and time services, security, and a standard remote procedure call interface. DCE for OpenVMS Alpha and OpenVMS I64 consists of the following four kits: - DCE Runtime Services Kit - DCE Application Development Kit - DCE CDS Server Kit - DCE Security Server Kit The right to use the Runtime Services Kit is included as part of the OpenVMS license. The other kits each require a separate license. You must install a kit on each system that will use DCE services. 2 KIT_DESCRIPTIONS 3 Runtime_Services_Kit The Runtime Services Kit provides the services necessary to execute and manage DCE applications. The Runtime Services Kit includes: - DCE Control Program (DCECP) - Authenticated CDS Advertiser and Client Support - CDS Browser - CDS Control Program (CDSCP) - Authenticated DCE RPC runtime support (supports DECnet, TCP, and UDP) - Security Client Support - A DCE_LOGIN tool for obtaining credentials. - A RGY_EDIT tool for registry maintenance functions - KINIT, KLIST, and KDESTROY Kerberos tools - Name Services Interface Daemon (nsid); also known as the PC Nameserver Proxy - Online help (OSF DCE reference manual pages) 3 Application_Development_Kit The Application Development Kit provides the services and tools necessary to develop, execute, and manage DCE applications. The Application Development Kit includes: - The contents of the Runtime Services Kit - Required DCE application development header files - Interface Definition Language (IDL) compiler - DCE RPC event logging facility - UUID generator - Sample DCE applications - Language-Sensitive Editor (LSE) templates for the Interface Definition Language - .H (Include) files and .IDL files for application development 3 CDS_Server_Kit The CDS Server Kit provides the naming services necessary for DCE clients to locate DCE server applications. The CDS Server kit includes the following: - CDS server (cdsd) - Global Directory Agent (gdad) The Global Directory Agent (GDA) lets you link multiple CDS namespaces using the Internet Domain Name System (DNS), X.500, or LDAP. 3 Security_Server_Kit The Security Server Kit provides security services necessary for authenticated RPC calls between DCE client and server applications to function. The Security Server kit includes the following: - Security server (secd) - Tool used to create the security database (sec_create_db) - Tool used to move the security database (sec_salvage_db) - Security server administrative tool (sec_admin) 2 HOW_TO_ACCESS_DCE_HELP_TOPICS This help library is created from the standard Open Group DCE documentation. It includes descriptions of additions that HP has made to the standard DCE; however, most interface issues specific to OpenVMS are not addressed. For information about using the universal interface and any information specific to the OpenVMS version of DCE, see the HP DCE for OpenVMS Alpha and OpenVMS I64 Product Guide. Note: Because HP DCE is a subset of the Open Group DCE, some of the information provided in this help library can mislead you into thinking a feature is available when it is not. This DCE help library lets you choose seven major help topics listed under DCE : DCE_CDS DCE_DTS DCE_IDL DCE_INTRO DCE_RPC DCE_SECURITY DCE_THREADS For example, to get help on RPC, enter the following: $ HELP DCE DCE_RPC User-level and system administration DCE commands are available at the top levels of the help files. This is the information that is stored in the man 1 and man 8 sections of other DCE systems. These commands have extensions such as (1rpc), (1dts), and (8cds) in the DCE reference manuals. Other reference material, including DCE routines and error messages, is available under the sections that correspond to pages in the reference manuals. For example, find the RPC application routines under RPC_Application_Routines and the DTS application routines under DTS_Application_Routines. A NOTE ABOUT UNDERSCORE CHARACTERS (_): To improve the searching capabilities of this OpenVMS help library, many topics contain underscore (_) characters between words. Note that some DCE commands also include underscore characters as part of their command syntax. Do not assume that the help topic name is the same as the command syntax to be entered as a command. Always check to see the actual command syntax. 3 Navigation_Hints USING WILDCARD CHARACTERS: Wildcard characters (* and %) are useful at the DCL ($) prompt or the "DCE Subtopic?" prompt. For example, to see the RPC application routines, enter the following command: $ HELP DCE DCE_RPC Application_R* To see all the DCE threads application routines, enter the following command: $ HELP DCE DCE_THREADS App* To directly access information about a routine, for example the routine rpc_binding_free, enter the following command: $ HELP DCE DCE_RPC Application_Routines rpc_binding_free You can shorten the syntax of the previous command to either of the following formats: $ HELP DCE DCE_RPC Appl* rpc_binding_free or $ HELP DCE DCE_RPC * rpc_binding_free However, you will get quicker response to direct routine queries if you use the full syntax of the command. Note that the user and administrative information such as rpccp is available at the top level as follows: $ help dce dce_rpc rpccp ACCESSING MESSAGES: To access message information enter a command with underscore (_) characters connecting key words, as shown in the following example: $ help dce dce_idl idl_m *interface_cannot_import* DCE IDL_Messages(rpc7) A_nonlocal_interface_cannot_import_a_local_interface Explanation: The [local] interface attribute implies that the interface is not part of an RPC application, but is used only to generate header files. This causes IDL to suppress any errors specific to RPC that the interface uses as part of an RPC application. User Action: Remove the [local] attribute from the imported interface definition. The imported interface does not need a UUID unless the interface defines an operation and you compile it independently. ACCESSING HELP SUBTOPICS FROM LONG LISTS: You can access subsections of help topics that contain long lists of additional information even while the "press RETURN to continue..." prompt is displayed. For example, when you enter the following command the system displays a long list of the message topics available: $ help dce dce_idl idl_message You may need to press RETURN several times before the system displays the message that you want. When the exact message topic is displayed you can access it quickly, however. Enter the correct message text at the "press RETURN to continue..." prompt, as shown in the following example: . . . A_maybe_operation_cannot_have_out_parameters_or_a_function_result A_min_is_parameter_must_have_the_in_attribute A_min_is_variable_must_be_a_small,_short,_or_long_integer A_nonlocal_interface_cannot_import_a_local_interface A_parameter_must_have_either_or_both_the_in_and_out_attributes . . . press RETURN to continue... *interface_cannot_import* Workstation users may find it easier to use the window cut-and-paste feature to enter long strings containing underscore (_) characters. 2 DCE_INTRO NAME DCE_INTRO - Introduction to the DCE routines DESCRIPTION The DCE routines provide several facilities that are applicable across more than one DCE component. They can be divided into the following major areas: DCE attribute interface routines These routines allow applications to define and access attribute types (schema entries) in a schema of your choice. They are based on the Extended Registry Attribute (ERA) interface, which defines and accesses attribute types in the register database schema. For more information about the individual attribute interface routines, see the dce_attr_intro reference page. DCE configuration routines These routines return information based on the contents of the local DCE configuration file, which is created during the DCE cell-configuration or machine-configuration process. For more information about the individual configuration routines, see the dce_cf_intro reference page. DCE backing store routines These routines allow you to maintain typed data between program invocations. The backing store routines can be used in servers, in clients or in standalone programs that do not involve remote procedure calls (RPC). For more information about the individual backing store routines, see the dce_db_intro reference page. DCE messaging interface routines These routines give you access to message catalogs, to specific message texts and message IDs, and to in-memory message tables. For more information about the individual messaging interface routines, see the dce_msg_intro reference page. DCE server routines These routines are used by servers to register themselves with DCE. This includes RPC runtime, the local endpoint mapper, and the namespace. Routines are also available to set up DCE security so that servers can receive and invoke authenticated RPCs. For more information about the individual server routines, see the dce_server_intro reference page. DCE serviceability routines These routines are intended for use by servers that export the serviceability interface defined in service.idl. There are also a set of DCE serviceability macros can be used for diagnostic purposes, and to create a serviceability handle. For more information about the individual serviceability routines, see the dce_svc_intro reference page. For more information about the individual DCE serviceability macros, see the DCE_SVC_INTRO_2 reference page. DCE Host daemon application programming interface These routines give management applications remote access to various data, servers, and services on DCE hosts. For more information about the individual host daemon application programming interface routines, see the dced_intro reference page. 3 dce_attr_intro NAME dce_attr_intro - Introduction to the DCE Attribute Interface routines DESCRIPTION The DCE Attribute Interface API allows applications to define and access attributes types (schema entries) in a schema of your choice. It is based on the Extended Registry Attribute (ERA) interface, which defines and accesses attribute types in the registry database schema. Except for the binding methods, the two APIs are similar. Note however, that the Extended Registry Attribute API provides routines to create attribute types in the registry schema, to create and manipulate attribute instances, and to attach those instances to objects. The DCE Attribute Interface in its current state provides calls only to create attribute types. For general usage guidelines for the DCE Attribute Interface refer to the chapter in this manual titled "The Extended Attribute Application Program Interface." The DCE Attribute Interface routine reference pages are supplied in this section. The DCE Attribute Interface Routines The DCE Attribute Interface consists of the following routines: dce_attr_sch_bind Returns an opaque handle of type dce_attr_sch_handle_t to a schema object specified by name and sets authentication and authorization parameters for the handle. dce_attr_sch_bind_free Releases an opaque handle of type dce_attr_sch_handle_t. dce_attr_sch_create_entry Creates a schema entry in a schema bound to with dce_attr_sch_bind. dce_attr_sch_update_entry Updates a schema entry in a schema bound to with dce_attr_sch_bind. dce_attr_sch_delete_entry Deletes a schema entry in a schema bound to with dce_attr_sch_bind. dce_attr_sch_scan Reads a specified number of schema entries. dce_attr_sch_cursor_init Allocates resources to and initializes a cursor used with dce_attr_sch_scan. The dce_attr_sch_cursor_init routine makes a remote call that also returns the current number of schema entries in the schema. dce_attr_sch_cursor_alloc Allocates resources to a cursor used with dce_attr_sch_scan. The dce_attr_sch_cursor_alloc routine is a local operation. dce_attr_sch_cursor_release Releases states associated with a cursor created by dce_attr_sch_cursor_alloc or dce_attr_sch_cursor_init. dce_attr_sch_cursor_reset Reinitializes a cursor used with dce_attr_sch_scan. The reset cursor can then be reused without releasing and re-allocating. dce_attr_sch_lookup_by_id Reads a schema entry identified by attribute type UUID. dce_attr_sch_lookup_by_name Reads a schema entry identified by attribute name. dce_attr_sch_get_acl_mgrs Retrieves the manager types of the ACLs protecting objects dominated by a named schema. dce_attr_sch_aclmgr_strings Returns printable ACL strings associated with an ACL manager protecting a schema object. Data Types and Structures dce_attr_sch_handle_t An opaque handle to a schema object. Use dce_attr_sch_bind to acquire the handle. dce_attr_component_name_t A pointer to a character string used to further specify a schema object. dce_bind_auth_info_t A enumeration that defines whether or not the binding is authenticated. This data type is defined exactly as the sec_attr_bind_auth_info_t data type in the ERA interface. See the sec_intro reference page for more information on sec_attr_bind_auth_info_t. dce_attr_schema_entry_t A structure that defines a complete attribute entry for the schema catalog. This data type is defined exactly as the sec_attr_schema_entry_t data type in the ERA interface. See the sec_intro reference page for more information on sec_attr_schema_entry_t. dce_attr_cursor_t A structure that provides a pointer into a database and is used for multiple database operations. This cursor must minimally represent the object indicated by dce_attr_sch_handle_t. The cursor may additionally represent an entry within that schema. dce_attr_schema_entry_parts_t A 32-bit bitset containing flags that specify the schema entry fields that can be modified on a schema entry update operation. This data type is defined exactly as the sec_attr_schema_entry_parts_t data type in the ERA interface. See the sec_intro reference page for more information on sec_attr_schema_entry_parts_t. 4 dce_attr_sch_bind NAME dce_attr_sch_bind - Return an opaque handle to a schema object SYNOPSIS #include void dce_attr_sch_bind( dce_attr_component_name_t schema_name, dce_bind_auth_info_t *auth_info, dce_attr_sch_handle_t *h, error_status_t *status ); PARAMETERS Input schema_name A pointer to a value of type dce_attr_component_name_t that specifies the name of the schema object to bind to. auth_info A value of type dce_bind_auth_info_t that defines the authentication and authorization parameters to use with the binding handle. If set to NULL, the default authentication and authorization parameters are used. Output h An opaque handle of type dce_attr_sch_handle_t to the named schema object for use with dce_attr_sch operations. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_bind() routine returns an opaque handle of type dce_attr_sch_handle_t to a named schema object. The returned handle can then be used for subsequent dce_attr_sch operations performed on the object. Permissions Required The dce_attr_sch_update_entry() routine requires appropriate permissions on the schema object. These permissions are managed by the target server. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL The idl file from which dce/dce_attr_base.h was derived. ERRORS dce_attr_s_bad_name sec_login_s_no_current_context rpc_s_entry_not_found rpc_s_no_more_bindings dce_attr_s_unknown_auth_info_type dce_attr_s_no_memory error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_bind_free 4 dce_attr_sch_bind_free NAME dce_attr_sch_bind_free - Releases an opaque handle of type dce_attr_sch_handle_t to a schema object SYNOPSIS #include void dce_attr_sch_bind_free( dce_attr_sch_handle_t *h, error_status_t *status ); PARAMETERS Input h An opaque handle of type dce_attr_sch_handle_t. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_bind_free() routine releases an opaque handle of type dce_attr_sch_handle_t. The handle was returned with the dce_attr_sch_bind() routine and used to perform dce_attr_sch operations. Permissions Required The dce_attr_sch_bind_free() routine requires appropriate permissions on the schema object. These permissions are managed by the target server. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_SCH.IDL The idl file from which dce/dce_attr_sch.h was derived. ERRORS error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_bind 4 dce_attr_sch_create_entry NAME dce_attr_sch_create_entry - Create a schema entry in a schema bound to by a previous dce_attr_sch_bind() routine SYNOPSIS #include void dce_attr_sch_create_entry( dce_attr_sch_handle_t h, dce_attr_schema_entry_t *schema_entry, error_status_t *status ); PARAMETERS Input h An opaque handle bound to a schema object. Use dce_attr_sch_bind() to acquire the handle. schema_entry A pointer to a dce_attr_schema_entry_t that contains the schema entry values for the schema in which the entry is to be created. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_create_entry() routine creates schema entries that define attribute types in the schema object bound to by h. Permissions Required The dce_attr_sch_create_entry() routine requires appropriate permissions on the schema object. These permissions are managed by the target server. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL The idl file from which dce/dce_attr_base.h was derived. ERRORS dce_attr_s_bad_binding error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_delete_entry dce_attr_sch_update 4 dce_attr_sch_update_entry NAME dce_attr_sch_update_entry - Update a schema entry SYNOPSIS #include void dce_attr_sch_update_entry( dce_attr_sch_handle_t h, dce_attr_schema_entry_parts_t modify_parts, dce_attr_schema_entry_t *schema_entry, error_status_t *status ); PARAMETERS Input h An opaque handle bound to a schema object. Use dce_attr_sch_bind() to acquire the handle. modify_parts A value of type dce_attr_schema_entry_parts_t that identifies the fields in the schema bound to by h that can be modified. schema_entry A pointer to a dce_attr_schema_entry_t that contains the schema entry values for the schema entry to be updated. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_update_entry() routine modifies schema entries. Only those schema entry fields set to be modified in the dce_attr_schema_entry_parts_t data type can be modified. Some schema entry components can never be modified. Instead to make any changes to these components, the schema entry must be deleted (which deletes all attribute instances of that type) and recreated. These components are listed below: + Attribute name + Reserved flag + Apply defaults flag + Intercell action flag + Trigger binding + Comment Fields that are arrays of structures (such as acl_mgr_set and trig_binding) are completely replaced by the new input array. This operation cannot be used to add a new element to the existing array. Permissions Required The dce_attr_sch_update_entry() routine requires appropriate permissions on the schema object. These permissions are managed by the target server. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL The idl file from which dce/dce_attr_base.h was derived. ERRORS dce_attr_s_bad_binding error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_delete_entry dce_attr_sch_create_entry 4 dce_attr_sch_delete_entry NAME dce_attr_sch_delete_entry - Delete a schema entry SYNOPSIS #include void dce_attr_sch_delete_entry( dce_attr_sch_handle_t h, uuid_t *attr_id, error_status_t *status ); PARAMETERS Input h An opaque handle bound to a schema object. Use dce_attr_sch_bind() to acquire the handle. attr_id A pointer to a uuid_t that identifies the schema entry to be deleted in the schema bound to by h. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_delete_entry() routine deletes a schema entry. Because this is a radical operation that invalidates any existing attributes of this type on objects dominated by the schema, access to this operation should be severely limited. Permissions Required The dce_attr_sch_delete_entry() routine requires requires appropriate permissions on the schema object. These permissions are managed by the target server. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL The idl file from which dce/dce_attr_base.h was derived. ERRORS dce_attr_s_bad_binding error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_create_entry dce_attr_sch_update_entry 4 dce_attr_sch_scan NAME dce_attr_sch_scan - Read a specified number of schema entries SYNOPSIS #include void dce_attr_sch_scan( dce_attr_sch_handle_t h, dce_attr_cursor_t *cursor, unsigned32 num_to_read, unsigned32 *num_read, dce_attr_schema_entry_t schema_entries[], error_status_t *status ); PARAMETERS Input h An opaque handle bound to a schema object. Use dce_attr_sch_bind() to acquire the handle. num_to_read An unsigned 32-bit integer specifying the size of the schema_entries[] array and the maximum number of entries to be returned. Input/Output cursor A pointer to a dce_attr_cursor_t. As input cursor must be allocated and can be initialized. If cursor is not initialized, dce_attr_sch_scan will initialize it. As output, cursor is positioned at the first schema entry after the returned entries. Output num_read A pointer to an unsigned 32-bit integer specifying the number of entries returned in schema_entries[]. schema_entries[] A dce_attr_schema_entry_t that contains an array of the returned schema entries. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_scan() routine reads schema entries. The read begins at the entry at which the input cursor is positioned and ends after the number of entries specified in num_to_read. The input cursor must have been allocated by either the dce_attr_sch_cursor_init() or the dce_attr_sch_cursor_alloc() call. If the input cursor is not initialized, dce_attr_sch_scan() initializes it; if cursor is initialized, dce_attr_sch_scan() simply advances it. To read all entries in a schema, make successive dce_attr_sch_scan() calls. When all entries have been read, the call returns the message no_more_entries. This routine is useful as a browser. Permissions Required The dce_attr_sch_scan() routine requires requires appropriate permissions on the schema object. These permissions are managed by the target server. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL The idl file from which dce/dce_attr_base.h was derived. ERRORS dce_attr_s_bad_binding dce_attr_s_bad_cursor error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_cursor_init dce_attr_sch_cursor_alloc dce_attr_sch_cursor_release 4 dce_attr_sch_cursor_init NAME dce_attr_sch_cursor_init - Initialize and allocate a cursor used with the dce_attr_sch_scan call SYNOPSIS #include void dce_rgy_attr_cursor_init( dce_attr_sch_handle_t h, unsigned32 *cur_num_entries, dce_attr_cursor_t *cursor, error_status_t *status ); PARAMETERS Input h An opaque handle bound to a schema object. Use dce_attr_sch_bind() to acquire the handle. Output cur_num_entries A pointer to an unsigned 32-bit integer that specifies the total number of entries contained in the schema at the time of this call. cursor A pointer to a dce_attr_cursor_t that is initialized to the first entry in the the schema. status A pointer to the completion status. On successful completion, the call returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_cursor_init() call initializes and allocates a cursor used with the dce_attr_sch_scan call. This call makes remote calls to initialize the cursor. To limit the number of remote calls, use the dce_attr_sch_cursor_alloc() call to allocate cursor, but not initialize it. If the cursor input to dce_attr_sch_scan has not been initialized, dce_attr_sch_scan call will initialize it; if it has been initialized, dce_attr_sch_scan advances it. Unlike the dce_attr_sch_cursor_alloc() call, the dce_attr_sch_cursor_init() call supplies the total number of entries found in the schema as an output parameter. Permissions Required None. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL The idl file from which dce/dce_attr_base.h was derived. ERRORS dce_attr_s_bad_binding dce_attr_s_no_memory error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_cursor_release dce_attr_sch_scan dce_attr_sch_cursor_allocate 4 dce_attr_sch_cursor_alloc NAME dce_attr_sch_cursor_alloc - Allocates resources to a cursor used with the dce_attr_sch_scan call SYNOPSIS #include void dce_rgy_attr_cursor_alloc( dce_attr_cursor_t *cursor, error_status_t *status ); PARAMETERS Output cursor A pointer to a dce_attr_cursor_t. status A pointer to the completion status. On successful completion, the call returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_cursor_alloc() call allocates resources to a cursor used with the dce_attr_sch_scan call. This routine, which is a local operation, does not initialize cursor. The dce_attr_sch_cursor_init() routine, which makes a remote call, allocates and initializes the cursor. In addition, dce_attr_sch_cursor_init() returns the total number of entries found in the schema as an output parameter; dce_attr_sch_cursor_alloc() does not. Permissions Required The dce_attr_sch_cursor_alloc() call requires appropriate permissions on the schema object. These permissions are managed by the target server. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL The idl file from which dce/dce_attr_base.h was derived. ERRORS dce_attr_s_no_memory error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_cursor_init dce_attr_sch_cursor_release dce_attr_sch_scan 4 dce_attr_sch_cursor_release NAME dce_attr_sch_cursor_release - Release states associated with a cursor that has been allocated with either dce_attr_sch_cursor_init() or dce_attr_sch_cursor_alloc(). SYNOPSIS #include void dce_attr_sch_cursor_init( dce_attr_cursor_t *cursor, error_status_t *status ); PARAMETERS Input/Output cursor A pointer to a dce_attr_cursor_t. As an input parameter, cursor must have been initialized to the first entry in a schema. As an output parameter, cursor is uninitialized with all resources released. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_cursor_init() routine releases the resources allocated to a cursor that has been allocated by either a dce_attr_sch_cursor_init() or dce_attr_sch_cursor_alloc(). This call is a local operation and makes no remote calls. Permissions Required None. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL The idl file from which dce/dce_attr_base.h was derived. ERRORS error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_cursor_init dce_attr_sch_cursor_alloc dce_attr_sch_cursor_reset dce_attr_sch_scan 4 dce_attr_sch_cursor_reset NAME dce_attr_sch_cursor_reset - Resets a cursor that has been allocated with either dce_attr_sch_cursor_init() or dce_attr_sch_cursor_alloc(). SYNOPSIS #include void dce_attr_cursor_reset( dce_attr_cursor_t *cursor, error_status_t *status ); PARAMETERS Input/Output cursor A pointer to a dce_attr_cursor_t. As an input parameter, an initialized cursor. As an output parameter, cursor is reset to the first attribute in the schema. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_cursor_reset() routine resets a dce_attr_cursor_t that has been allocated by either a dce_attr_sch_cursor_init() or dce_attr_sch_cursor_alloc(). The reset cursor can then be used to process a new dce_attr_sch_scan query by reusing the cursor instead of releasing and re-allocating it. This is a local operation and makes no remote calls. Permissions Required None. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_SCH.IDL The idl file from which dce/dce_attr_sch.h was derived. ERRORS error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_cursor_init dce_attr_sch_cursor_alloc dce_attr_sch_scan 4 dce_attr_sch_lookup_by_id NAME dce_attr_sch_lookup_by_id - Read a schema entry identified by UUID SYNOPSIS #include void dce_attr_sch_lookup_by_id( dce_attr_sch_handle_t h, uuid_t *attr_id, dce_attr_schema_entry_t *schema_entry, error_status_t *status ); PARAMETERS Input h An opaque handle bound to a schema object. Use dce_attr_sch_bind() to acquire the handle. attr_id A pointer to a uuid_t that identifies a schema entry. Output schema_entry A dce_attr_schema_entry_t that contains an entry identified by attr_id. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_lookup_by_id() routine reads a schema entry identified by attr_id. This routine is useful for programmatic access. Permissions Required The dce_attr_sch_lookup_by_id() routine requires appropriate permissions on the schema object. These permissions are managed by the target server. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL The idl file from which dce/dce_attr_base.h was derived. ERRORS dce_attr_s_bad_binding error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_lookup_by_name dce_attr_sch_scan 4 dce_attr_sch_lookup_by_name NAME dce_attr_sch_lookup_by_name - Read a schema entry identified by name SYNOPSIS #include void dce_attr_sch_lookup_by_name( dce_attr_sch_handle_t h, char *attr_name, dce_attr_schema_entry_t *schema_entry, error_status_t *status ); PARAMETERS Input h An opaque handle bound to a schema object. Use dce_attr_sch_bind() to acquire the handle. attr_name A pointer to a character string that identifies the schema entry. Output schema_entry A dce_attr_schema_entry_t that contains the schema entry identified by attr_name. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_lookup_by_name() routine reads a schema entry identified by name. This routine is useful for use with an interactive editor. Permissions Required The dce_attr_sch_lookup_by_name() routine requires appropriate permissions on the schema object. These permissions are managed by the target server. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL The idl file from which dce/dce_attr_base.h was derived. ERRORS dce_attr_s_bad_binding error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_lookup_by_id dce_attr_sch_scan 4 dce_attr_sch_get_acl_mgrs NAME dce_attr_sch_get_acl_mgrs - Retrieve the manager types of the ACLs protecting the objects dominated by a named schema SYNOPSIS #include void dce_attr_sch_get_acl_mgrs( dce_attr_sch_handle_t h, unsigned32 size_avail, unsigned32 *size_used, unsigned32 *num_acl_mgr_types, uuid_t acl_mgr_types[], error_status_t *status ); PARAMETERS Input h An opaque handle bound to a schema object. Use dce_attr_sch_bind() to acquire the handle. size_avail An unsigned 32-bit integer containing the allocated length of the acl_manager_types[] array. Output size_used An unsigned 32-bit integer containing the number of output entries returned in the acl_mgr_types[] array. num_acl_mgr_types An unsigned 32-bit integer containing the number of types returned in the acl_mgr_types[] array. This may be greater than size_used if there was not enough space allocated by size_avail for all the manager types in the acl_manager_types[] array. acl_mgr_types[] An array of the length specified in size_avail to contain UUIDs (of type uuid_t) identifying the types of ACL managers protecting the target object. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_attr_sch_get_acl_mgrs() routine returns a list of the manager types protecting the schema object identified by h. ACL editors and browsers can use this operation to determine the ACL manager types protecting a selected schema object. Then, using the dce_attr_sch_aclmgr_strings() routine, they can determine how to format for display the permissions supported by that ACL manager type. Permissions Required The dce_attr_sch_get_acl_mgrs() routine requires appropriate permissions on the schema object for which the ACL manager types are to be returned. These permissions are managed by the target server. FILES SYS$COMMON:[DCE$LIBRARY]DCE_ATTR_BASE.IDL The idl file from which dce/dce_attr_base.h was derived. ERRORS dce_attr_s_not_implemented error_status_ok RELATED INFORMATION Functions: dce_attr_intro dce_attr_sch_aclmgr_strings 3 dce_cf_intro NAME dce_cf_intro - Introduction to the DCE configuration routines DESCRIPTION The DCE configuration routines return information based on the contents of the local DCE configuration file, which is created during the DCE cell-configuration or machine-configuration process. A configuration file is located on each DCE machine; it contains the host's name, the primary name of the cell in which the host is located, and any aliases for that cell name. The configuration routines can also be used to get some additional information corollary to the hostname, namely: + The host's principal name. + Binding information to the host. The configuration file on machines that belong to internationalized DCE cells also contains the pathname to the code set registry object file on the host. The Security Service component on each DCE machine must be able to find out, by strictly local means, its machine's hostname, the host machine's principal name, and its cell's name. The DCE configuration routines exist primarily to enable Security components to do these things. But because this information can be useful to DCE applications as well, these routines are made available as part of the general application programming interface. Note that "hostname" as used throughout this section refers to the DCE hostname (that is, the machine's /.../cellname/host_directory/hostname entry in the CDS namespace), and not, for example, its DNS (Domain Name Service) hostname, which could be quite different from the DCE name. The DCE configuration routines are: dce_cf_binding_entry_from_host() Returns the host binding entry name. dce_cf_dced_entry_from_host() Returns the dced entry name on a host. dce_cf_find_name_by_key() Returns a string tagged by key (this is a lower-level utility routine that is used by the others). dce_cf_free_cell_aliases() Frees a list of cell aliases for a cell. dce_cf_get_cell_aliases() Returns a list of cell aliases for a cell. dce_cf_get_cell_name() Returns the primary cell name for the local cell. dce_cf_get_csrgy_filename() Returns the pathname of the local code set registry object file. dce_cf_get_host_name() Returns the hostname relative to a local cell. dce_cf_prin_name_from_host() Returns the host's principal name. dce_cf_profile_entry_from_host Returns the host's profile entry. dce_cf_same_cell_name() Indicates whether or not two cell names refer to the same cell. CAUTIONS The DCE 1.0 implementations of the DCE configuration routines will accept only lines (in the configuration file) whose length is less than 1024 characters. If a tag occurs more than once in the input, the routines will recognize only the first occurrence. FILES DCE$LOCAL:[000000]dce_cf.db The machine's local DCE configuration file (where DCE$LOCAL is usually something like DIA0:[SYS0.DCELOCAL.]). The format of the configuration file is as follows. Each of the entries is tagged with its own identifier, which must be the first nonblank token on a line that does not begin with a # (number sign) comment character. The second token on a line is assumed to be the name associated with the tag that was detected in front of it. For example, cellname and hostname are tags, identifying the cellname and hostname, respectively, for the machine on which the configuration file is located. A sample configuration file could have the following contents: cellname /.../osf.org hostname hosts/brazil which would identify the host brazil in the osf.org cell. Text characterized by the following is ignored: + Garbage lines; that is, lines that do not conform to the previously described format. + Leading and trailing spaces in lines. + Additional tokens appearing on a line after the second token. The configuration file should be writable only by privileged users, and readable by all. OUTPUT The DCE configuration routines return names without global or cell- relative prefixes, such as: host_directory/hostname or: principalname where: host_directory is usually hosts. However, the DCE NSI (Name Service Interface) routines require names passed to them to be expressed either in a cell-relative form, such as: /.:/host_directory/hostname or as global names, with the global root prefix /.../ and the cell name, such as: /.../cellname/host_directory/hostname Therefore, an application must add either the cell-relative (/.:/) or correct global (/.../cellname) prefix to any name it receives from a DCE configuration routine before it passes the name to an NSI routine. (NSI routines all have names beginning with rpc_ns_.) For example, the name host_directory/hostname would become, if expressed in cell-relative form: /.:/hosts/hostname The cell-relative form of the name principalname would be: /.:/sec/principals/principalname where: hostname and principalname are the host's name and principal name, respectively. RELATED INFORMATION BOOKS: OSF DCE Application Development Guide-Core Components OSF DCE Command Reference. FUNCTIONS: 4 dce_cf_binding_entry_from_host NAME dce_cf_binding_entry_from_host - Returns the host binding entry name SYNOPSIS #include void dce_cf_binding_entry_from_host( char *hostname, char **entry_name, error_status_t *status); PARAMETERS INPUT hostname - Specifies the name of the host. Note that host names are case sensitive. If NULL, the configuration file is searched for the hostname, and that name, if found, is used. OUTPUT entry_name - The binding entry name associated with the specified host. status - Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. Possible status codes and their meanings are as follows: dce_cf_st_ok Operation completed successfully. dce_cf_e_file_open File open error. dce_cf_e_no_mem No memory available. dce_cf_e_no_match No hostname entry in the DCE configuration file. DESCRIPTION The dce_cf_binding_entry_from_host() routine returns the binding entry name string associated with the hostname passed to it. If hostname is NULL, the binding entry name associated with the name returned by dce_cf_get_host_name() is returned. FILES DCE$LOCAL:[000000]dce_cf.db The machine's local DCE configuration file (where dcelocal is usually something like DIA0:[SYS0.DCELOCAL.]). RETURN VALUES No value is returned. RELATED INFORMATION BOOKS: OSF DCE Administration Guide. FUNCTIONS: dce_cf_find_name_by_key dce_cf_get_cell_name dce_cf_get_host_name dce_cf_prin_name_from_host 4 dce_cf_dced_entry_from_host NAME dce_cf_dced_entry_from_host - Returns the dced entry name on a host SYNOPSIS #include void dce_cf_dced_entry_from_host( char *hostname, char **entry_name, error_status_t *status); PARAMETERS INPUT hostname - Specifies the name of the host. Note that host names are case-sensitive. If this value is NULL, the value returned by dce_cf_get_host_name is used. OUTPUT entry_name - The dced entry name associated with the specified host. Storage for this name is dynamically allocated; release it with free() when you no longer need it. status - Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. Possible status codes and their meanings are as follows: dce_cf_st_ok Operation completed successfully. dce_cf_e_file_open File open error. dce_cf_e_no_mem No memory available. dce_cf_e_no_match No hostname entry in the DCE configuration file. DESCRIPTION The dce_cf_dced_entry_from_host() routine returns the name entered into the DCE namespace for a DCE host daemon (dced) on the host specified by the hostname parameter. If the hostname parameter is NULL, the dced name associated with the name returned by dce_cf_get_host_name() is returned. The string name is of the form /.:/hosts/hostname/config, and specifies the entry point into the dced namespace on the host. This is the location in the DCE namespace at which dced stores the objects associated with the host services it provides (the hostdata, srvrconf, srvrexec, secval, and keytab services, as well as ACL editing). It is also an actual name in the DCE namespace that you can import if you want to create your own RPC binding to dced. You can use the dced entry name returned by this routine as input to the dced_binding_create() routine, input to sec_acl_* routines, or to rpc_ns_binding_import_* routines to establish a binding to a dced host service. If using dced_binding_create(), you append a service name to the entry returned by this routine. If using sec_acl_* routines, you append the service and the object name. If using rpc_ns_binding_import_*, you use only the entry returned by the routine. You can also use the returned string to name objects that dced maintains, for example, when editing these objects' ACLs with dcecp. For example, the string name /.:/hosts/vineyard/config/srvrconf/dtsd names the server configuration data for the DTS server on the host vineyard. FILES DCE$LOCAL:[000000]dce_cf.db The machine's local DCE configuration file (where dcelocal is usually something like DIA0:[SYS0.DCELOCAL.]). RETURN VALUES No value is returned. RELATED INFORMATION FUNCTIONS: dce_cf_binding_entry_from_host dce_cf_find_name_by_key dce_cf_get_cell_name dce_cf_get_host_name dce_cf_prin_name_from_host dced_binding_create BOOKS: OSF DCE Application Development Guide-Core Components OSF DCE Com mand Reference. 4 dce_cf_find_name_by_key NAME dce_cf_find_name_by_key - Returns a string tagged by a character string key SYNOPSIS #include void dce_cf_find_name_by_key( FILE *fp, char *key, char **name, error_status_t *status); PARAMETERS INPUT fp - A file pointer to a correctly formatted text file opened for reading. key - A character string key that will be used to find name. INPUT/OUTPUT name - A pointer to a string (char **) in which a string containing the name found will be placed. The name string will be allocated by malloc(). OUTPUT status - Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. Possible status codes and their meanings are as follows: dce_cf_st_ok Operation completed succesfully. dce_cf_e_no_mem No memory available. dce_cf_e_no_match No match for key in the file. DESCRIPTION The dce_cf_find_name_by_key() routine searches a text file for the first occurrence of a string tag identical to the string passed in key. The tag string, in order to be found, must be the first non-white space string on an uncommented line. If the tag string is found, dce_cf_find_name_by_key() allocates (by a call to malloc()) a buffer for the next string found on the same line as the tag string, copies this second string into the buffer, and returns its address in the name input parameter. The name of the DCE configuration file is in the constant dce_cf_c_db_name; in turn, this constant is defined in the include file . CAUTIONS The memory for a returned name string is allocated by malloc(), and must be freed by the original caller of the configuration routine that called dce_cf_find_name_by_key(). The DCE 1.0 version of this routine is limited to processing lines of text whose length is less than 1024 characters. FILES DCE$LOCAL/dce_cf.db The machine's local DCE configuration file (where dcelocal is usually something like DIA0:[SYS0.DCELOCAL.]). RETURN VALUES No value is returned. RELATED INFORMATION FUNCTIONS: dce_cf_binding_entry_from_host dce_cf_get_cell_name dce_cf_get_host_name dce_cf_prin_name_from_host BOOKS: OSF DCE Administration Guide. 4 dce_cf_free_cell_aliases NAME dce_cf_free_cell_aliases - Frees a list of cell name aliases for the local cell SYNOPSIS #include void dce_cf_free_cell_aliases( char **cell_alias_list, error_status_t *status); PARAMETERS INPUT cell_alias_list - The address of a cell alias list, which is a null-terminated array of pointers to the cell alias names for the local cell. OUTPUT status - Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. Possible status codes and their meanings are as follows: dce_cf_st_ok Operation completed succesfully. dce_cf_e_file_open File open error. dce_cf_e_no_mem No memory available. dce_cf_e_no_match No match for key in the file. DESCRIPTION The dce_cf_free_cell_aliases() routine frees the list of aliases for the local cell that the dce_cf_free_cell_aliases() routine allocated. The routine frees the memory allocated to hold the array of pointers to cell alias string buffers, and also frees the string buffers. RETURN VALUES No value is returned. RELATED INFORMATION FUNCTIONS: dce_cf_get_cell_aliases dce_cf_get_cell_name dce_cf_get_host_name dce_cf_prin_name_from_host dce_cf_same_cell_name BOOKS: OSF DCE Application Development Guide-Core Components OSF DCE Command Reference. 4 dce_cf_get_cell_aliases NAME dce_cf_get_cell_aliases - Returns a list of aliases for the local cell SYNOPSIS #include void dce_cf_get_cell_aliases( char ***cell_alias_list, error_status_t *status); PARAMETERS INPUT None. OUTPUT cell_alias_list - The address of a string pointer array. This routine sets this address to point to the address of an allocated null-terminated array of pointers to the cell alias names for the local cell. If no aliases exist, the routine returns NULL in this parameter. status - Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. Possible status codes and their meanings are as follows: dce_cf_st_ok Operation completed succesfully. dce_cf_e_file_open File open error. dce_cf_e_no_mem No memory available. dce_cf_e_no_match No match for key in the file. DESCRIPTION The dce_cf_get_cell_aliases() routine retrieves the local cell's cell name aliases. If cell aliases are found, the routine returns the address of an allocated list of cell alias names in the cell_alias_list parameter. If no aliases exist for the cell, the routine returns NULL. Use the dce_cf_free_cell_aliases() routine to free the memory allocated by the dce_cf_get_cell_aliases() routine. RETURN VALUES No value is returned. RELATED INFORMATION FUNCTIONS: dce_cf_free_cell_aliases dce_cf_get_cell_name dce_cf_get_host_name dce_cf_same_cell_name BOOKS: OSF DCE Application Development Guide-Core Components, OSF DCE Command Reference. 4 dce_cf_get_cell_name NAME dce_cf_get_cell_name - Returns the primary name for the local cell SYNOPSIS #include void dce_cf_get_cell_name( char **cellname, error_status_t *status); PARAMETERS INPUT None. OUTPUT cellname - The address of a string pointer. This pointer will be set by the function to point to an allocated buffer that contains the cellname. OUTPUT status - Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. Possible status codes and their meanings are as follows: dce_cf_st_ok Operation completed succesfully. dce_cf_e_file_open File open error. dce_cf_e_no_mem No memory available. dce_cf_e_no_match No match for key in the file. DESCRIPTION The dce_cf_get_cell_name() routine retrieves the primary name for the local cell. If the name is found, dce_cf_get_cell_name() returns an allocated (by a call to malloc()) copy of it in the cellname input parameter. Use free() to free the allocated copy when you no longer need it. The DCE 1.0 version of this routine is limited to processing lines of text whose length is less than 1024 characters. RETURN VALUES No value is returned. RELATED INFORMATION FUNCTIONS: dce_cf_free_cell_aliases dce_cf_get_cell_aliases dce_cf_get_host_name dce_cf_prin_name_from_host BOOKS: OSF DCE Administration Guide. 4 dce_cf_get_csrgy_filename NAME dce_cf_get_csrgy_filename - Returns the pathname of the code set registry file on a host SYNOPSIS #include void dce_cf_get_csrgy_filename( char **csrgy_filename, error_status_t *status); PARAMETERS INPUT None. INPUT/OUTPUT csrgy_filename - The address of a string pointer. This pointer will be set by the function to point to a buffer that contains the pathname to the code set registry file. OUTPUT status - Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. Possible status codes and their meanings are as follows: dce_cf_st_ok Operation successfully completed. dce_cf_e_file_open File open error. dce_cf_e_no_mem No memory available. DESCRIPTION The dce_cf_get_csrgy_filename() routine is a DCE function that returns the pathname of a code set registry file that has been created on a given host with the csrc utility. DCE RPC routines for code set inter- operability use this routine when they need to locate a host's code set registry file in order to map between unique code set identifiers and their operating system-specific local code set names, or to obtain supported code sets for a client or server. User-written code set interoperability routines can also use the routine. The dce_cf_get_csrgy_filename() routine searches the DCE configuration file for the name of the local host's code set registry file, allocates a buffer for it (by a call to malloc()), copies the name into the buffer, and returns its address in the csrgy_filename input parameter. CAUTIONS The memory for a returned name string is allocated by malloc(), and must be freed by the caller of dce_cf_get_csrgy_filename(). The DCE 1.0 verion of this routine is limited to processing lines of text whose length is less than 1024 characters. FILES DCE$LOCAL:[000000]dce_cf.db The machine's local DCE configuration file (where dcelocal is usually something like DIA0:[SYS0.DCELOCAL.]). RETURN VALUES No value is returned. RELATED INFORMATION FUNCTIONS: dce_cf_get_cell_name dce_cf_find_name_by_key dce_cf_get_host_name dce_cf_prin_name_from_host dce_loc_to_rgy dce_rgy_to_loc rpc_rgy_get_codesets COMMANDS: csrc. BOOKS: OSF DCE Administration Guide. 4 dce_cf_get_host_name NAME dce_cf_get_host_name - Returns the hostname relative to the local cell root SYNOPSIS #include void dce_cf_get_host_name( char **hostname, error_status_t *status); PARAMETERS INPUT None. INPUT/OUTPUT hostname - The address of a string pointer. This pointer will be set by the function to point to a buffer that contains the hostname. OUTPUT status - Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. Possible status codes and their meanings are as follows: dce_cf_st_ok Operation successfully completed. dce_cf_e_file_open File open error. dce_cf_e_no_mem No memory available. dce_cf_e_no_match No hostname entry in the DCE configuration file. DESCRIPTION The dce_cf_get_host_name() routine searches the DCE configuration file for the local host's name relative to the local cell's root. If the name is found, dce_cf_get_host_name() allocates (by a call to malloc()) a buffer for it, copies the name into the buffer, and returns its address in the hostname input parameter. CAUTIONS The memory for a returned name string is allocated by malloc(), and must be freed by the caller of dce_cf_get_host_name(). The DCE 1.0 version of this routine is limited to processing lines of text whose length is less than 1024 characters. FILES DCE$LOCAL:[000000]dce_cf.db The machine's local DCE configuration file (where dcelocal is usually something like DIA0:[SYS0.DCELOCAL.]). RETURN VALUES No value is returned. RELATED INFORMATION FUNCTIONS: dce_cf_binding_entry_from_host dce_cf_find_name_by_key dce_cf_get_cell_name dce_cf_prin_name_from_host BOOKS: OSF DCE Administration Guide. 4 dce_cf_prin_name_from_host NAME dce_cf_prin_name_from_host - Returns the host's principal name SYNOPSIS #include void dce_cf_prin_name_from_host( char *hostname, char **prin_name, error_status_t *status); PARAMETERS INPUT hostname - The name of the host. Note that host names are case sensitive. If NULL, the configuration file is searched for the hostname, and that name, if found, is used. OUTPUT prin_name - The principal name associated with the specified host. status - Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. Possible status codes and their meanings are as follows: dce_cf_st_ok Operation completed successfully. dce_cf_e_file_open File open error. dce_cf_e_no_mem No memory available. dce_cf_e_no_match No hostname entry in the DCE configuration file. DESCRIPTION The dce_cf_prin_name_from_host() routine returns the principal name associated with the hostname passed to it. If hostname is NULL, dce_cf_prin_name_from_host() returns the principal name associated with the name returned by dce_cf_get_host_name(). FILES DCE$LOCAL:[000000]dce_cf.db The machine's local DCE configuration file (where dcelocal is usually something like DIA0:[SYS0.DCELOCAL.]). RETURN VALUES No value is returned. RELATED INFORMATION FUNCTIONS: dce_cf_binding_entry_from_host dce_cf_find_name_by_key dce_cf_get_cell_name dce_cf_get_host_name BOOKS: OSF DCE Administration Guide. 4 dce_cf_profile_entry_from_host NAME dce_cf_profile_entry_from_host - Returns the host profile entry SYNOPSIS #include void dce_cf_profile_entry_from_host( char *hostname, char **prof_name, error_status_t *status); PARAMETERS INPUT hostname - Specifies the name of the host. Note that host names are case sensitive. If NULL, the configuration file is searched for the hostname, and that name, if found, is used. OUTPUT prof_name - The profile entry associated with the specified host. status - Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. Possible status codes and their meanings are as follows: dce_cf_st_ok Operation completed successfully. dce_cf_e_file_open File open error. dce_cf_e_no_mem No memory available. dce_cf_e_no_match No hostname entry in the DCE configuration file. DESCRIPTION The dce_cf_profile_entry_from_host() routine returns the profile entry string associated with the hostname passed to it. If hostname is NULL, the profile entry associated with the name returned by dce_cf_get_host_name() is returned. FILES DCE$LOCAL:[000000]dce_cf.db The machine's local DCE configuration file (where dcelocal is usually something like DIA0:[SYS0.DCELOCAL.]). RETURN VALUES No value is returned. RELATED INFORMATION FUNCTIONS: dce_cf_find_name_by_key dce_cf_get_cell_name dce_cf_get_host_name dce_cf_prin_name_from_host dce_cf_binding_entry_from_host BOOKS: OSF DCE Administration Guide. 4 dce_cf_same_cell_name NAME dce_cf_same_cell_name - Indicates whether or not two cell names refer to the same cell SYNOPSIS #include void dce_cf_same_cell_name( char *cell_name1, char *cell_name2, boolean result, error_status_t *status); PARAMETERS INPUT cell_name1 - A character string that specifies the name of a cell. cell_name2 - A character string that specifies the name of a cell to compare with cell_name1. If this value is NULL, the routine determines whether or not the cell name specified in cell_name1 is the name of the local cell. OUTPUT result - A boolean value that indicates whether or not the specified cell names match, when two cell names are given, and indicates whether or not the specified cell name is the name of the local cell, when only one cell name is given. A value of TRUE indicates that the cell names refer to the same cell. status - Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. Possible status codes are as follows: dce_cf_st_ok Operation completed successfully. dce_cf_e_no_match No hostname entry in the DCE configuration file. DESCRIPTION The dce_cf_same_cell_name () routine, when given the names of two cells as input parameters, compares the cell names to determine whether or not they refer to the same call. The result parameter is set to TRUE if they do, and to FALSE if they do not. If only one cell name is specified as an input parameter, the dce_cf_same_cell_name() routine determines whether or not the specified cell name is the same as the local cell's primary name (which it retrieves by calling dce_cf_get_cell_name()). You can use the routine in this way to determine whether a given cell name is the primary name of your local cell. RETURN VALUES No value is returned. RELATED INFORMATION FUNCTIONS: dce_cf_free_cell_aliases dce_cf_get_cell_aliases dce_cf_get_cell_name BOOKS: OSF DCE Application Development Guide-Core Components OSF DCE Command Reference 3 dce_db_intro NAME dce_db_intro - Introduction to the DCE backing store interface DESCRIPTION The DCE backing store interface allows you to maintain typed data between program invocations. For example, you might store application- specific configuration data in a backing store, and then retrieve it from the backing store when the application restarts. The backing store routines can be used in servers, in clients or in standalone programs that do not involve remote procedure calls (RPC). A program can have more than one backing store open at the same time. Sometimes the backing store is called a database. For instance, the associated IDL file is dce/database.idl, and the name of the backing store routines begin with dce_db_. The backing store is, however, not a full-fledged database in the conventional sense, and it has no support for SQL or for any other query system. BACKING STORE DATA The backing store interface provides for the tagged storage and retrieval of typed data. The tag (or retrieval key) can be either a UUID or a standard C string. For a specific backing store, the data type must be specified at compile time, and is established through the IDL Encoding Services. Each backing store can contain only a single data type. Each data item (also called a data object or data record) consists of the data stored by a single call to a storage routine (dce_db_store(), dce_db_store_by_name(), or dce_db_store_by_uuid()). Optionally, data items can have headers. If a backing store has been created to use headers, then every data item must have a header. For a description of the data item header, see "Data Structures," below. ENCODING AND DECODING IN THE BACKING STORE When a Remote Procedure Call (RPC) sends data between a client and a server, it serializes the user's data structures by using the IDL Encoding Services (ES), described in the OSF DCE Application Development Guide. The backing store uses this same serialization scheme for encoding and decoding, informally called "pickling," when storing data structures to disk. The IDL compiler, idl, writes the routine that encodes and decodes the data. This routine is passed to dce_db_open(), remembered in the handle, and used by the store and fetch routines: + dce_db_fetch() + dce_db_fetch_by_name() + dce_db_fetch_by_uuid() + dce_db_header_fetch() + dce_db_store() + dce_db_store_by_name() + dce_db_store_by_uuid() MEMORY ALLOCATION When fetching data, the Encoding Services (ES) allocate memory for the data structures that are returned. These services accept a structure, and use rpc_sm_allocate() to provide additional memory needed to hold the data. The backing store library does not know what memory has been allocated, and therefore cannot free it. For fetch calls that are made from a server stub, this is not a problem, because the memory is freed automatically when the server call terminates. For fetch calls that are made from a non-server, the programmer is responsible for freeing the memory. Programs that call the fetch or store routines, such as dce_db_fetch(), outside of a server operation (for instance, if a server does some backing store initialization, or in a standalone program) must call rpc_sm_enable_allocate() first. THE BACKING STORE ROUTINES Many of the backing store routines appear in three versions: plain, by name, and by UUID. The plain version will work with backing stores that were created to be indexed either by name, or by UUID, while the restricted versions accept only the matching type. It is advantageous to use the restricted versions when they are appropriate, because they provide type checking by the compiler, as well as visual clarity of purpose. The backing store routines are as follows, listed in alphabetical order: dce_db_close() Frees the handle returned by dce_db_open(). It closes any open files and releases all other resources associated with the backing store. dce_db_delete() Deletes an item from a backing store that is indexed by name or by UUID. The key's type must match the flag that was used in dce_db_open(). dce_db_delete_by_name() Deletes an item only from a backing store that is indexed by name. dce_db_delete_by_uuid() Deletes an item only from a backing store that is indexed by UUID. dce_db_fetch() Retrieves data from a backing store that is indexed by name or by UUID. The key's type must match the flag that was used in dce_db_open(). dce_db_fetch_by_name() Retrieves data only from a backing store that is indexed by name. dce_db_fetch_by_uuid() Retrieves data only from a backing store that is indexed by UUID. dce_db_free() Releases the data supplied from a backing store. dce_db_header_fetch() Retrieves a header from a backing store. dce_db_inq_count() Returns the number of items in a backing store. dce_db_iter_done() Terminates and iteration operation initiated by dce_db_iter_start(). It should be called when iteration is done. dce_db_iter_next() Returns the key for the next item from a backing store that is indexed by name or by UUID. The db_s_no_more return value indicates that there are no more items. dce_db_iter_next_by_name() Returns the key for the next item only from a backing store that is indexed by name. The db_s_no_more return value indicates that there are no more items. dce_db_iter_next_by_uuid() Returns the key for the next item only from a backing store that is indexed by UUID. The db_s_no_more return value indicates that there are no more items. dce_db_iter_start() Prepares for the start of iteration. dce_db_lock() Locks a backing store. A lock is associated with an open backing store's handle. The storage routines, dce_db_store(), dce_db_store_by_name(), and dce_db_store_by_uuid(), all acquire the lock before updating. dce_db_open() Creates a new backing store or opens an existing one. The backing store is identified by a filename. Flags allow you to: + Create a new backing store, or open an existing one. + Create a new backing store indexed by name, or indexed by UUID. + Open an existing backing store read/write, or read-only. + Use the standard data item header, or not. The routine returns a handle by which subsequent routines can reference the opened backing store. dce_db_std_header_init() Initializes a standard backing store header retrieved by dce_db_header_fetch(). It only places the values into the header, and does not write into the backing store. dce_db_store() Stores a data item into a backing store that is indexed by name or by UUID. The key's type must match the flag that was used in dce_db_open(). dce_db_store_by_name() Stores a data item only into a backing store that is indexed by name. dce_db_store_by_uuid() Stores a data item only into a backing store that is indexed by UUID. dce_db_unlock() Unlocks a backing store. DATA TYPES AND STRUCTURES dce_db_handle_t An opaque handle to a backing store. Use dce_db_open() to acquire the handle. dce_db_header_t The data structure that defines a standard backing store header for data items. Use dce_db_header_fetch() to retrieve it from a backing store and dce_db_std_header_init() to initialize it. dce_db_convert_func_t An opaque pointer to the data conversion function to be used when storing or retrieving data. This function is specified as an argument to dce_db_open() at open time. It converts between native format and on-disk (serialized) format. It is generated from the IDL file by the IDL compiler. CAUTIONS You can not use conformant arrays in objects stored to a backing store. This is because the idl-generated code that encodes (pickles) the structure has no way to predict or detect the size of the array. When the object is fetched, there will likely be insufficient space provided for the structure, and the array's data will destroy whatever is in memory after the structure. FILES database.idl, database.h, db.h, and dbif.h RELATED INFORMATION BOOKS: OSF DCE Application Development Guide 4 dce_db_close NAME dce_db_close - Closes an open backing store SYNOPSIS #include #include void dce_db_close( dce_db_handle_t *handle, error_status_t *status ); PARAMETERS Input handle A handle identifying the backing store to be closed. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_db_close() routine closes a backing store that was opened by dce_db_open(). It also frees the storage used by the handle, and sets the handle's value to NULL. ERRORS error_status_ok The call was successful. RELATED INFORMATION Functions: dce_db_open 4 dce_db_delete NAME dce_db_delete - Deletes an item from a backing store SYNOPSIS #include #include void dce_db_delete( dce_db_handle_t handle, void *key, error_status_t *status ); PARAMETERS Input handle A handle, returned from dce_db_open(), that identifies the backing store being used. key A pointer to a string or UUID that is the key to the item in the backing store. The datatype of key must match the key method that was selected in the flags parameter to dce_db_open() when the backing store was created. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error code. DESCRIPTION The dce_db_delete() routine deletes an item from the backing store that is identified by the handle parameter, which was obtained from dce_db_open(). It is a general deletion routine, interpreting the key parameter according to the type of index with which the backing store was created. ERRORS db_s_del_failed The deletion did not occur. The global variable errno may indicate further information about the error. db_s_bad_index_type The key's type is wrong, or the backing store is not by name or by UUID. db_s_iter_not_allowed The function was called while an iteration, begun by dce_db_iter_start(), was in progress. Deletion is not allowed during iteration. error_status_ok The call was successful. RELATED INFORMATION Functions: dce_db_delete_by_name dce_db_delete_by_uuid dce_db_open 4 dce_db_delete_by_name NAME dce_db_delete_by_name - Deletes an item from a string-indexed backing store SYNOPSIS #include #include void dce_db_delete_by_name( dce_db_handle_t handle, char *key, error_status_t *status ); PARAMETERS Input handle A handle, returned from dce_db_open(), that identifies the backing store being used. key A NULL-terminated string that is the key to the item in the backing store. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error code. DESCRIPTION The dce_db_delete_by_name() routine deletes an item from the backing store that is identified by the handle parameter, which was obtained from dce_db_open(). It is a specialized deletion routine for backing stores that are indexed by name, as selected by the db_c_index_by_name bit in the flags parameter to dce_db_open() when the backing store was created. ERRORS db_s_del_failed The deletion did not occur. The global variable errno may indicate further information about the error. db_s_bad_index_type The backing store is not indexed by name. db_s_iter_not_allowed The function was called while an iteration, begun by dce_db_iter_start(), was in progress. Deletion is not allowed during iteration. error_status_ok The call was successful. RELATED INFORMATION Functions: dce_db_delete dce_db_delete_by_uuid dce_db_open 4 dce_db_delete_by_uuid NAME dce_db_delete_by_uuid - Deletes an item from a UUID-indexed backing-store SYNOPSIS #include #include void dce_db_delete_by_uuid( dce_db_handle_t handle, uuid_t *key, error_status_t *status ); PARAMETERS Input handle A handle, returned from dce_db_open(), that identifies the backing-store being used. key A pointer to a UUID that is the key to the item in the backing store. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error code. DESCRIPTION The dce_db_delete_by_uuid() routine deletes an item from the backing-store that is identified by the handle parameter, which was obtained from dce_db_open(). It is a specialized deletion routine for backing stores that are indexed by UUID, as selected by the db_c_index_by_uuid bit in the flags parameter to dce_db_open() when the backing store was created. ERRORS db_s_del_failed The deletion did not occur. The global variable errno may indicate further information about the error. db_s_bad_index_type The backing-store is not indexed by UUID. db_s_iter_not_allowed The function was called while an iteration, begun by dce_db_iter_start(), was in progress. Deletion is not allowed during iteration. error_status_ok The call was successful. RELATED INFORMATION Functions: dce_db_delete dce_db_delete_by_name dce_db_open 4 dce_db_fetch NAME dce_db_fetch - Retrieves data from a backing store SYNOPSIS #include #include void dce_db_fetch( dce_db_handle_t handle, void *key, void *data, error_status_t *status ); PARAMETERS Input handle A handle, returned from dce_db_open(), that identifies the backing store being used. key A string or UUID that is the key to the item in the backing store. The datatype of key must match the key method that was selected in the flags parameter to dce_db_open() when the backing store was created. Output data A pointer to the returned data. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_db_fetch() routine retrieves data from the backing store that is identified by the handle parameter, which was obtained from dce_db_open(). It is a general retrieval routine, interpreting the key parameter according to the type of index with which the backing store was created. The data parameter is shown as a pointer to an arbitrary data type. In actual use it will be the address of the backing-store- specific data type. NOTES After calling dce_db_fetch(), it may be necessary to free some memory, if the call was made outside of an RPC, on the server side. This is done by calling rpc_sm_client_free(). (Inside an RPC the memory is allocated through rpc_sm_allocate(), and is automatically freed.) Programs that call dce_db_fetch() outside of a server operation (for instance, if a server does some backing store initialization, or in a standalone program) must call rpc_sm_enable_allocate() first. Indeed, every thread that calls dce_db_fetch() must do rpc_sm_allocate(), but in the server side of an RPC, this is already done. ERRORS db_s_key_not_found The specified key was not found in the backing store. (This circumstance is not necessarily an error.) db_s_bad_index_type The key's type is wrong, or else the backing store is not by name or by UUID. error_status_ok The call was successful. RELATED INFORMATION Functions: dce_db_fetch_by_name dce_db_fetch_by_uuid dce_db_free dce_db_open 4 dce_db_fetch_by_name NAME dce_db_fetch_by_name - Retrieves data from a string-indexed backing store SYNOPSIS #include #include void dce_db_fetch_by_name( dce_db_handle_t handle, char *key, void *data, error_status_t *status ); PARAMETERS Input handle A handle, returned from dce_db_open(), that identifies the backing store being used. key A null-terminated string that is the key to the item in the backing store. Output data A pointer to the returned data. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_db_fetch_by_name() routine retrieves data from the string-indexed backing store that is identified by the handle parameter, which was obtained from dce_db_open(). It is a specialized retrieval routine for backing stores that are indexed by string, as selected by the db_c_index_by_name bit in the flags parameter to dce_db_open() when the backing store was created. The data parameter is shown as a pointer to an arbitrary data type. In actual use it will be the address of the backing-store-specific data type. NOTES After calling dce_db_fetch_by_name(), it may be necessary to free some memory, if the call was made outside of an RPC, on the server side. This is done by calling rpc_sm_client_free(). (Inside an RPC the memory is allocated through rpc_sm_allocate(), and is automatically freed.) Programs that call dce_db_fetch_by_name() outside of a server operation (for instance, if a server does some backing store initialization, or in a standalone program) must call rpc_sm_enable_allocate() first. Indeed, every thread that calls dce_db_fetch_by_name() must do rpc_sm_allocate(), but in the server side of an RPC, this is already done. EXAMPLES This example shows the use of the user-defined data type as the data parameter. extern dce_db_handle_t db_h; uuid_t key_uuid; my_data_type_t my_data; error_status_t status; /* set key_uuid = xxx; */ dce_db_fetch_by_name(db_h, &key_uuid, &my_data, &status); ERRORS db_s_key_not_found The specified key was not found in the backing store. (This circumstance is not necessarily an error.) db_s_bad_index_type The backing store is not indexed by name. error_status_ok The call was successful. RELATED INFORMATION Functions: dce_db_fetch dce_db_fetch_by_uuid dce_db_free dce_db_open 4 dce_db_fetch_by_uuid NAME dce_db_fetch_by_uuid - Retrieves data from a UUID-indexed backing store SYNOPSIS #include #include void dce_db_fetch_by_uuid( dce_db_handle_t handle, uuid_t *key, void *data, error_status_t *status ); PARAMETERS Input handle A handle, returned from dce_db_open(), that identifies the backing store being used. key A UUID that is the key to the item in the backing store. Output data A pointer to the returned data. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_db_fetch_by_uuid() routine retrieves data from the UUID-indexed backing store that is identified by the handle parameter, which was obtained from dce_db_open(). It is a specialized retrieval routine for backing stores that are indexed by UUID, as selected by the db_c_index_by_uuid bit in the flags parameter to dce_db_open() when the backing store was created. The data parameter is shown as a pointer to an arbitrary data type. In actual use it will be the address of the backing-store-specific data type. NOTES After calling dce_db_fetch_by_uuid(), it may be necessary to free some memory, if the call was made outside of an RPC, on the server side. This is done by calling rpc_sm_client_free(). (Inside an RPC the memory is allocated through rpc_sm_allocate(), and is automatically freed.) Programs that call dce_db_fetch_by_uuid() outside of a server operation (for instance, if a server does some backing store initialization, or in a standalone program) must call rpc_sm_enable_allocate() first. Indeed, every thread that calls dce_db_fetch_by_uuid() must do rpc_sm_allocate(), but in the server side of an RPC, this is already done. EXAMPLES This example shows the use of the user-defined data type as the data parameter. extern dce_db_handle_t db_h; uuid_t key_uuid; my_data_type_t my_data; error_status_t status; /* set key_uuid = xxx; */ dce_db_fetch_by_uuid(db_h, &key_uuid, &my_data, &status); ERRORS db_s_key_not_found The specified key was not found in the backing store. (This circumstance is not necessarily an error.) db_s_bad_index_type The backing store is not indexed by UUID. error_status_ok The call was successful. RELATED INFORMATION Functions: dce_db_fetch dce_db_fetch_by_name dce_db_free dce_db_open 4 dce_db_free NAME dce_db_free - Releases the data supplied from a backing store SYNOPSIS #include #include void dce_db_free( dce_db_handle_t handle, void *data, error_status_t *status ); PARAMETERS Input handle A handle, returned from dce_db_open(), that identifies the backing store being used. data The data area to be released. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_db_free() routine is designed to free the data area previously returned via a call to dce_db_fetch(), dce_db_fetch_by_name(), or dce_db_fetch_by_uuid(). NOTES In the current implementation, the dce_db_free() routine does not perform any action. For servers that execute properly this is of little consequence, because their allocated memory is automatically cleaned up when a remote procedure call finishes. For completeness, and for compatibility with future releases, the use of dce_db_free() is recommended. ERRORS error_status_ok The call was successful. RELATED INFORMATION Functions: dce_db_fetch dce_db_fetch_by_name dce_db_fetch_by_uuid 4 dce_db_header_fetch NAME dce_db_header_fetch - Retrieves the header from a backing store SYNOPSIS #include #include void dce_db_header_fetch( dce_db_handle_t handle, void *key, dce_db_header_t *hdr, error_status_t *status ); PARAMETERS Input handle A handle, returned from dce_db_open(), that identifies the backing store being used. key A string or UUID that is the backing store key. Output hdr A pointer to a caller-supplied header structure to be filled in by the library. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_db_header_fetch() routine returns a pointer to a copy of the header of the object in the backing store that is identified by the handle parameter, which was obtained from dce_db_open(). The caller must free the copy's storage. It was allocated (as with other fetch routines) through rpc_ss_alloc(). The key parameter is interpreted according to the type of index with which the backing store was created. The hdr parameter is shown as a pointer to an arbitrary data type. In actual use it will be the address of the backing-store-specific data type. ERRORS db_s_key_not_found The key was not found in the backing store. error_status_ok The call was successful. RELATED INFORMATION Functions: dce_db_fetch dce_db_std_header_init 4 dce_db_inq_count NAME dce_db_inq_count - Returns the number of items in a backing store SYNOPSIS #include #include void dce_db_inq_count( dce_db_handle_t handle, unsigned32 *count, error_status_t *status ); PARAMETERS Input handle A handle, returned from dce_db_open(), that identifies the backing store being used. Output count A pointer to the number of items in the backing store. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_db_inq_count() routine returns the number of items in the backing store that is identified by the handle parameter, which was obtained from dce_db_open(). It performs identically on backing stores that are indexed by UUID and those that are indexed by string. The count of items can be helpful when iterating through a backing store. ERRORS db_s_iter_not_allowed The function was called while an iteration, begun by dce_db_iter_start(), was in progress. Determining the count is not allowed during iteration. error_status_ok The call was successful. RELATED INFORMATION Functions: dce_db_iter_next 4 dce_db_iter_done NAME dce_db_iter_done - Frees the state associated with iteration SYNOPSIS #include #include void dce_db_iter_done( dce_db_handle_t handle, error_status_t *status ); PARAMETERS Input handle A handle, returned from dce_db_open(), that identifies the backing store being used. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. DESCRIPTION The dce_db_iter_done() routine frees the state that permits iteration. It should be called after an iteration through a backing store is finished. The iteration state is established by dce_db_iter_start(). The routines for performing iteration over the items are dce_db_iter_next(), dce_db_iter_next_by_name(), and dce_db_iter_next_by_uuid(). ERRORS error_status_ok The call was successful. RELATED INFORMATION Functions: dce_db_iter_next dce_db_iter_next_by_name dce_db_iter_next_by_uuid dce_db_iter_start 4 dce_db_iter_next NAME dce_db_iter_next - During iteration, returns the next key from a backing store SYNOPSIS #include #include void dce_db_iter_next( dce_db_handle_t handle, void **key, error_status_t *status ); PARAMETERS Input handle A handle, returned from dce_db_open(), that identifies the backing store being used. Output key A pointer to the string or UUID that is the key to the item in the backing store. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_db_iter_next() routine retrieves the next key from the backing store that is identified by the handle parameter. An iterator established by the dce_db_iter_start() routine maintains the identity of the current key. Use one of the dce_db_fetch() routines to retrieve the actual data. The iteration functions scan sequentially through a backing store, in no particular order. The dce_db_iter_start() routine initialized the process, a dce_db_iter_next() routine retrieves successive keys, for which the data can be retrieved with dce_db_fetch(), and the dce_db_iter_done() routine finishes the process. The iteration can also use the dce_db_iter_next_by_name() and dce_db_iter_next_by_uuid() routines; the fetching can use the dce_db_fetch_by_name() and dce_db_fetch_by_uuid() routines. The iteration routine returns a pointer to a private space associated with the handle. Each call to the iteration routine reuses the space, instead of using allocated space. ERRORS db_s_no_more All the keys in the backing store have been accessed; there are no more iterations remaining to be done. error_status_ok The call was successful. RELATED INFORMATION Functions: dce_db_fetch dce_db_fetch_by_name dce_db_fetch_by_uuid dce_db_iter_done dce_db_iter_next_by_name dce_db_iter_next_by_uuid dce_db_iter_start 4 dce_db_iter_next_by_name NAME dce_db_iter_next_by_name - During iteration, returns the next key from a backing store indexed by string SYNOPSIS #include #include void dce_db_iter_next_by_name( dce_db_handle_t handle, char **key, error_status_t *status ); PARAMETERS Input handle A handle, returned from dce_db_open(), that identifies the backing store being used. Output key The string that is the key to the item in the backing store. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_db_iter_next_by_name() routine retrieves the next key from the backing store that is identified by the handle parameter. An iterator established by the dce_db_iter_start() routine maintains the identity of the current key. Use the dce_db_fetch_by_name() routine to retrieve the actual data. This iteration routine is the same as dce_db_iter_next(), except that it only works with backing stores indexed by name, and returns an error if the backing store index is the wrong type. The iteration routine returns a pointer to a private space associated with the handle. Each call to the iteration routine reuses the space, instead of using allocated space. ERRORS db_s_no_more All the keys in the backing store have been accessed; there are no more iterations remaining to be done. error_status_ok The call was successful. RELATED INFORMATION Functions: dce_db_fetch_by_uuid dce_db_iter_done dce_db_iter_next dce_db_iter_next_by_uuid dce_db_iter_start 4 dce_db_iter_next_by_uuid NAME dce_db_iter_next_by_uuid - During iteration, returns the next key from a backing store indexed by UUID SYNOPSIS #include #include void dce_db_iter_next_by_uuid( dce_db_handle_t handle, uuid_t **key, error_status_t *status ); PARAMETERS Input handle A handle, returned from dce_db_open(), that identifies the backing store being used. Output key The UUID that is the key to the item in the backing store. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_db_iter_next_by_uuid() routine retrieves the next key from the backing store that is identified by the handle parameter. An iterator established by the dce_db_iter_start() routine maintains the identity of the current key. Use the dce_db_fetch_by_uuid() routine to retrieve the actual data. This iteration routine is the same as dce_db_iter_next(), except that it only works with backing stores indexed by UUID, and returns an error if the backing store index is the wrong type. The iteration routine returns a pointer to a private space associated with the handle. Each call to the iteration routine reuses the space, instead of using allocated space. ERRORS error_status_ok The call was successful. RELATED INFORMATION Functions: dce_db_iter_done dce_db_iter_next dce_db_iter_next_by_name dce_db_iter_start 4 dce_db_iter_start NAME dce_db_iter_start - Prepares a backing store for iteration SYNOPSIS #include #include void dce_db_iter_start( dce_db_handle_t handle, error_status_t *status ); PARAMETERS Input handle A handle, returned from dce_db_open(), that identifies the backing store being used. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. DESCRIPTION The dce_db_iter_start() routine prepares the backing store that is identified by the handle parameter for iterative retrieval of all its keys in succession. A given handle can support only a single instance of iteration at one time. To avoid the possibility that another thread will write to the backing store during an iteration, always use the dce_db_lock() routine before calling dce_db_iter_start(). ERRORS db_s_iter_not_allowed The function was called while an iteration was already in progress. The concept of nested iterations is not supported. error_status_ok The call was successful. RELATED INFORMATION Functions: dce_db_iter_done dce_db_iter_next dce_db_iter_next_by_name dce_db_iter_next_by_uuid dce_db_lock dce_db_unlock dce_db_open 4 dce_db_lock NAME dce_db_lock - Applies an advisory lock on a backing store SYNOPSIS #include #include void dce_db_lock( dce_db_handle_t handle, error_status_t *status ); PARAMETERS Input handle A handle, returned from dce_db_open(), that identifies the backing store being used. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_db_lock() routine acquires the lock associated with the handle. There is an advisory lock associated with each handle. The routines for storing and deleting backing stores apply the lock before updating a backing store. This routine provides a means to apply the lock for other purposes, such as iteration. Advisory locks allow cooperating threads to perform consistent operations on backing stores, but do not guarantee consistency; that is, threads may still access backing stores without using advisory locks, possibly resulting in inconsistencies. ERRORS db_s_already_locked An attempt was made to lock a backing store, but it was already locked. error_status_ok The call was successful. RELATED INFORMATION Functions: dce_db_delete dce_db_delete_by_name dce_db_delete_by_uuid dce_db_store dce_db_store_by_name dce_db_store_by_uuid dce_db_unlock 4 dce_db_open NAME dce_db_open - Opens an existing backing store or creates a new one SYNOPSIS #include #include void dce_db_open( const char *name, const char *backend_type, unsigned32 flags, dce_db_convert_func_t convert, dce_db_handle_t *handle, error_status_t *status ); PARAMETERS Input name The filename of the backing store to be opened or created. backend_type Either of the strings, bsd4.4-hash or bsd4.4-btree, or a null pointer, which defaults to hash. This parameter specifies the backing store backend type for licensees adding multiple backends. flags The manner of opening, as specified by any of the following bits: db_c_index_by_name The backing store is to be indexed by name. Either this or db_c_index_by_uuid, but not both, must be selected. db_c_index_by_uuid The backing store is to be indexed by UUID. Either this or db_c_index_by_name, but not both, must be selected. db_c_std_header The first field of each item (which is defined as a union in dce_db_header_t) is the standard backing store header, with the case dce_db_header_std selected. The selection for header cannot have both db_c_std_header and db_c_acl_uuid_header. If neither header flag is specified, no header is used. db_c_acl_uuid_header The first field of each item (the union) is an ACL UUID, with the case dce_db_header_acl_uuid selected. The selection for header cannot have both db_c_std_header and db_c_acl_uuid_header. If neither header flag is specified, no header is used. db_c_readonly An existing backing store is to be opened in read-only mode. Read/write is the default. db_c_create Creates an empty backing store if one of the given name does not already exist. It is an error to try to create an existing backing store. convert The function, generated by the IDL compiler, that is called to perform serialization. Output handle A pointer to a handle that identifies the backing store being used. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_db_open() routine opens the specified backing store. The flags parameter must specify whether the backing store is to be indexed by name or by UUID. If all of a server's objects have entries in the CDS namespace, then it is probably best to use a UUID index. If the server provides a junction or another name-based lookup operation, then it is probably best to use a name index. The IDL code in /usr/include/dce/database.idl defines the backing store header (selected by the flags parameter) that is placed on each item, the possible header types, and the form of the function for serializing headers. NOTES Backing stores are also called databases. For instance, the associated IDL header is dce/database.idl, and the name of the backing store routines begin with dce_db_. Nevertheless, backing stores are not databases in the conventional sense, and have no support for SQL or for any other query system. EXAMPLES Standardized use of the backing store library is encouraged. The following is the skeleton IDL interface for a server's backing store: interface XXX_db { import "dce/database.idl"; typedef XXX_data_s_t { dce_db_header_t header; /* server-specific data */ } XXX_data_t; void XXX_data_convert( [in] handle_t h, [in, out] XXX_data_t *data, [out] error_status_t *st ); } This interface should be compiled with the following ACF: interface XXX_db { [encode, decode] XXX_data_convert(); } A typical call to dce_db_open(), using the preceding IDL example, would be: dce_db_open( "XXX_db", NULL, db_c_std_header | db_c_index_by_uuid, (dce_db_convert_func_t)XXX_data_convert, &handle, &st ); ERRORS db_s_bad_index_type The index type in flags is specified neither by name nor by UUID; or else it is specified as both. db_s_bad_header_type The header type in flags is specified as both standard header and ACL header. db_s_index_type_mismatch An existing backing store was opened with the wrong index type. db_s_open_already_exists The backing store file specified for creation already exists. db_s_no_name_specified No filename is specified. db_s_open_failed_eacces The server does not have permission to open the backing store file. db_s_open_failed_enoent The specified directory or backing store file was not found. db_s_open_failed The underlying database-open procedure failed. The global variable errno may provide more specific information. error_status_ok The call was successful. RELATED INFORMATION Functions: dce_db_close 4 dce_db_std_header_init NAME dce_db_std_header_init - Initializes a standard backing store header SYNOPSIS #include #include void dce_db_std_header_init( dce_db_handle_t handle, dce_db_header_t *hdr, uuid_t *uuid, uuid_t *acl_uuid, uuid_t *def_object_acl, uuid_t *def_container_acl, unsigned32 ref_count, error_status_t *status ); PARAMETERS Input handle A handle, returned from dce_db_open(), that identifies the backing store being used. hdr Pointer to the object header part of the users' structure. uuid The UUID to be placed into the header. Can be NULL. acl_uuid The UUID of the ACL protecting this object, to be placed into the header. Can be NULL. def_object_acl The UUID of the default object ACL, to be placed into the header. Can be NULL. def_container_acl The UUID of the default container ACL, to be placed into the header. Can be NULL. ref_count The reference count to be placed into the header. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_db_std_header_init() routine initializes the fields of the standard header for a data object whose backing store is identified by the handle parameter. The fields are only set in memory and should be stored to the backing store by one of the store routines. The handle was obtained from dce_db_open(), which must have been called with the db_c_std_header flag. ERRORS db_s_bad_header_type The header type is not dce_db_header_std. error_status_ok The call was successful. RELATED INFORMATION Functions: dce_db_header_fetch 4 dce_db_store NAME dce_db_store - Stores data into a backing store SYNOPSIS #include #include void dce_db_store( dce_db_handle_t handle, void *key, void *data, error_status_t *status ); PARAMETERS Input handle A handle, returned from dce_db_open(), that identifies the backing store being used. key A string or UUID that is the backing store key. The datatype of key must match the key method that was selected in the flags parameter to dce_db_open() when the backing store was created. data A pointer to the data structure to be stored. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_db_store() routine stores the data structure pointed to by data into the backing store. The conversion function that was specified in the call to dce_db_open() serializes the structure so that it can be written to disk. If the key value is the same as a key already stored, the new data replaces the previously stored data associated with that key. NOTES Because the dce_db_store() routine uses the encoding services, and they in turn use rpc_sm_allocate(), all programs that call dce_db_store() outside of a server operation (for instance, if a server does some backing store initialization, or in a standalone program) must call rpc_sm_enable_allocate() first. Indeed, every thread that calls dce_db_store() must do rpc_sm_enable_allocate(), but in the server side of an RPC, this is already done. ERRORS db_s_bad_index_type The key's type is wrong, or else the backing store is not by name or by UUID. db_s_readonly The backing store was opened with the db_c_readonly flag, and cannot be written to. db_s_store_failed The data could not be stored into the backing store for some reason. The global variable errno may contain more information about the error. db_s_iter_not_allowed The function was called while an iteration, begun by dce_db_iter_start(), was in progress. Storing is not allowed during iteration. error_status_ok The call was successful. RELATED INFORMATION Functions: dce_db_fetch dce_db_open dce_db_store_by_name dce_db_store_by_uuid 4 dce_db_store_by_name NAME dce_db_store_by_name - Stores data into a string-indexed backing store SYNOPSIS #include #include void dce_db_store_by_name( dce_db_handle_t handle, char *key, void *data, error_status_t *status ); PARAMETERS Input handle A handle, returned from dce_db_open(), that identifies the backing store being used. key A null-terminated string that is the backing store key. data A pointer to the data structure to be stored. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_db_store_by_name() routine stores the data structure pointed to by data into the backing store. The conversion function that was specified in the call to dce_db_open() serializes the structure so that it can be written to disk. This routine is specialized for storage into backing stores that are indexed by string, as selected by the db_c_index_by_name bit in the flags parameter to dce_db_open() when the backing store was created. If the key value is the same as a key already stored, the new data replaces the previously stored data associated with that key. NOTES Because the dce_db_store_by_name() routine uses the encoding services, and they in turn use rpc_sm_allocate(), all programs that call dce_db_store_by_name() outside of a server operation (for instance, if a server does some backing store initialization, or in a standalone program) must call rpc_sm_enable_allocate() first. Indeed, every thread that calls dce_db_store_by_name() must do rpc_sm_enable_allocate(), but in the server side of an RPC, this is already done. ERRORS db_s_bad_index_type The backing store is not indexed by name. db_s_readonly The backing store was opened with the db_c_readonly flag, and cannot be written to. db_s_store_failed The data could not be stored into the backing store for some reason. The global variable errno may contain more information about the error. db_s_iter_not_allowed The function was called while an iteration, begun by dce_db_iter_start(), was in progress. Storing is not allowed during iteration. error_status_ok The call was successful. RELATED INFORMATION Functions: dce_db_open dce_db_store dce_db_store_by_uuid 4 dce_db_store_by_uuid NAME dce_db_store_by_uuid - Stores data into a UUID-indexed backing store SYNOPSIS #include #include void dce_db_store_by_uuid( dce_db_handle_t handle, uuid_t *key, void *data, error_status_t *status ); PARAMETERS Input handle A handle, returned from dce_db_open(), that identifies the backing store being used. key A UUID that is the backing store key. data A pointer to the data structure to be stored. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_db_store_by_uuid() routine stores the data structure pointed to by data into the backing store. The conversion function that was specified in the call to dce_db_open() serializes the structure so that it can be written to disk. This routine is specialized for storage into backing stores that are indexed by UUID, as selected by the db_c_index_by_uuid bit in the flags parameter to dce_db_open() when the backing store was created. If the key value is the same as a key already stored, the new data replaces the previously stored data associated with that key. NOTES Because the dce_db_store_by_uuid() routine uses the encoding services, and they in turn use rpc_sm_allocate(), all programs that call dce_db_store_by_uuid() outside of a server operation (for instance, if a server does some backing store initialization, or in a standalone program) must call rpc_sm_enable_allocate() first. Indeed, every thread that calls dce_db_store_by_uuid() must do rpc_sm_enable_allocate(), but in the server side of an RPC, this is already done. ERRORS db_s_bad_index_type The backing store is not indexed by UUID. db_s_readonly The backing store was opened with the db_c_readonly flag, and cannot be written to. db_s_store_failed The data could not be stored into the backing store for some reason. The global variable errno may contain more information about the error. db_s_iter_not_allowed The function was called while an iteration, begun by dce_db_iter_start(), was in progress. Storing is not allowed during iteration. error_status_ok The call was successful. RELATED INFORMATION Functions: dce_db_open dce_db_store dce_db_store_by_name 4 dce_db_unlock NAME dce_db_unlock - Releases the backing store lock SYNOPSIS #include #include void dce_db_unlock( dce_db_handle_t handle, error_status_t *status ); PARAMETERS Input handle A handle, returned from dce_db_open(), that identifies the backing store being used. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The dce_db_unlock() routine releases the lock associated with the handle. ERRORS db_s_not_locked An attempt was made to unlock a backing store, but it was not locked. error_status_ok The call was successful. RELATED INFORMATION Functions: dce_db_lock 3 dce_msg_intro NAME dce_msg_intro - Introduction to the DCE messaging interface DESCRIPTION All DCE message texts are assigned a unique message ID. This is a 32-bit number, with the special value of all-bits-zero reserved to indicate success. All other numbers are divided into a technology/component that identifies the message catalog, and an index into the catalog. All messages for a given component are stored in a single message catalog generated by the sams utility when the component is built. (The messages may also be compiled into the application code, rendering the successful retrieval of message text independent of whether or not the message catalogs were correctly installed.) In typical use, a message is first retrieved from a message catalog, allowing localization to occur. If this fails, the default message is retrieved from an in-memory table. If this fails, a fallback text identifying the message number is generated. The two most useful routines, dce_error_inq_text() and dce_msg_get(), and the DCE printf routines follow these rules. The rest of this API gives direct access for special needs. The dce_msg_cat_xxx() routines provide a DCE abstraction to standard message catalog routines, mapping DCE message IDs to message catalog names. They offer a convenient way of opening and accessing a message catalog simply by supplying the ID of a message contained in it, rather than the name of the catalog itself. Once opened, the catalog is accessed by means of an opaque handle (the dce_msg_cat_handle_t typedef). THE DCE MESSAGING ROUTINES The messaging routines are as follows, listed in alphabetical order: dce_error_inq_text() Retrieves from the installed DCE component message catalogs the message text associated with an error status code returned by a DCE library routine. dce_fprintf() Functions much like dce_printf(), except that it prints the message and its arguments on the specified stream. dce_msg_cat_close() Closes the message catalog (which was opened with dce_msg_cat_open()). dce_msg_cat_get_msg() Retrieves the text for a specified message. dce_msg_cat_open() Opens the message catalog that contains the specified message, and returns a handle that can be used in subsequent calls to dce_msg_cat_get_msg(). dce_msg_define_msg_table() Registers an in-memory table containing the messages. dce_msg_get() Retrieves the text for a specified message. A "convenience" form of the dce_msg_get_msg() routine. dce_msg_get_cat_msg() A "convenience" form of the dce_msg_cat_get_msg() routine. Unlike dce_msg_cat_get_msg(), dce_msg_get_cat_msg() does not require the message catalog to be explicitly opened. dce_msg_get_default_msg() Retrieves a message from the application's in- memory tables. dce_msg_get_msg() Retrieves the text for a specified message. dce_msg_translate_table() The dce_msg_translate_table() routine overwrites the specified in-memory message table with the values from the equivalent message catalogs. dce_pgm_fprintf() Equivalent to dce_fprintf(), except that it prepends the program name and appends a newline. dce_pgm_printf() Equivalent to dce_printf(), except that it prepends the program name and appends a newline. dce_pgm_sprintf() Equivalent to dce_sprintf(), except that it prepends the program name and appends a newline. dce_printf() Retrieves the message text associated with the specified message ID, and prints the message and its arguments on the standard output. dce_sprintf() Retrieves the message text associated with the specified message ID, and prints the message and its arguments into an allocated string that is returned. DATA TYPES AND STRUCTURES dce_error_string_t An array of characters big enough to hold any error text returned by dce_error_inq_text(). dce_msg_cat_handle_t An opaque handle to a DCE message catalog. (Use dce_msg_cat_open() to get a handle.) FILES dce/dce_msg.h RELATED INFORMATION BOOKS: OSF DCE Application Development Guide 4 dce_error_inq_text NAME dce_error_inq_text - Retrieves message text associated with a DCE error code SYNOPSIS #include void dce_error_inq_text( error_status_t status_to_convert, dce_error_string_t error_text, int *status ); PARAMETERS Input status_to_convert DCE status code for which text message is to be retrieved. Output error_text The message text associated with the status_to_convert. status Returns the status code from this operation. The status code is set to 0 on success, and to -1 on failure. DESCRIPTION The dce_error_inq_text() routine retrieves from the installed DCE component message catalogs the message text associated with an error status code returned by a DCE library routine. All DCE message texts are assigned a unique 32-bit message ID. The special value of all-bits-zero is reserved to indicate success. The dce_error_inq_text() routine uses the message ID as a series of indices into the correct DCE component's message catalog; the text found by this indexing is the message that explains the status code that was returned by the DCE or DCE application routine. All messages for a given component are stored in a single message catalog generated by the sams utility when the component is built. (The messages may also be compiled into the component code, rendering the successful retrieval of message text independent of whether or not the message catalogs were correctly installed.) If the user sets their LANG variable and has the correct message catalog files installed, the user can receive translated messages. That is, the text string returned by dce_error_inq_text() is dependant on the current locale. EXAMPLES The following code fragment shows how dce_error_inq_text() can be used to retrieve the message text describing the status code returned by a DCE RPC library routine: dce_error_string_t error_string; error_status_t status; int print_status; rpc_server_register_if( application_v1_0_s_ifspec, &type_uuid, (rpc_mgr_epv_t)&manager_epv, &status ); if (status != rpc_s_ok) { dce_error_inq_text( status, error_string, &print_status ); fprintf( stderr, " Server: %s: %s\n", caller, error_string ); } 4 dce_msg_cat_close NAME dce_msg_cat_close - DCE message catalog close routine SYNOPSIS #include void dce_msg_cat_close( dce_msg_cat_handle_t handle, error_status_t *status ); PARAMETERS Input handle The handle (returned by dce_msg_cat_open()) to the catalog that is to be closed. Output status Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. DESCRIPTION The dce_msg_cat_close() routine closes the message catalog (which was opened with dce_msg_cat_open()). On error, it fills in status with an error code. ERROR CODES See dce_msg_get RELATED INFORMATION Functions: dce_msg_cat_get_msg dce_msg_cat_open dce_msg_get_cat_msg dce_msg_get dce_msg_get_msg 4 dce_msg_cat_get_msg NAME dce_msg_cat_get_msg - DCE message text retrieval routine SYNOPSIS #include unsigned char *dce_msg_cat_get_msg( dce_msg_cat_handle_t handle, unsigned32 message, error_status_t *status ); PARAMETERS Input message The ID of the message to be retrieved. handle A handle (returned by dce_msg_cat_open()) to an opened message catalog. Output status Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. DESCRIPTION Once the catalog has been opened with the dce_msg_cat_open() routine, the dce_msg_cat_get_msg() routine can be used to retrieve the text for a specified message (which is a 32-bit DCE message ID as described in dce_error_inq_text). If the specified message cannot be found in the catalog, the routine returns a NULL and fills in status with the appropriate error code. ERROR CODES See dce_msg_get. RELATED INFORMATION Functions: dce_msg_cat_close dce_msg_cat_open dce_msg_get_cat_msg dce_msg_get dce_msg_get_msg 4 dce_msg_cat_open NAME dce_msg_cat_open - DCE message catalog open routine SYNOPSIS #include dce_msg_cat_handle_t dce_msg_cat_open( unsigned32 message_ID, error_status_t *status ); PARAMETERS Input message_ID The ID of the message to be retrieved. Output status Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. DESCRIPTION The dce_msg_cat_open() routine opens the message catalog that contains the specified message_ID. It returns a handle that can be used in subsequent calls to dce_msg_cat_get_msg(). On error, it returns NULL and fills in status with an appropriate error code. ERROR CODES See dce_msg_get. RELATED INFORMATION Functions: dce_msg_cat_close dce_msg_cat_get_msg dce_msg_get_cat_msg dce_msg_get dce_msg_get_msg 4 dce_msg_define_msg_table NAME dce_msg_define_msg_table - Adds a message table to in-memory table SYNOPSIS #include void dce_msg_define_msg_table( dce_msg_table_t *table, unsigned32 count, error_status_t *status ); PARAMETERS Input table A message table structure (defined in a header file generated by sams during compilation (see the EXAMPLES section). count The number of elements contained in the table. Output status Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. DESCRIPTION All messages for a given component are stored in a single message catalog generated by the sams utility when the component (application) is built. However, the messages may also be compiled directly into the component code, thus rendering the successful retrieval of message text independent of whether or not the message catalogs were correctly installed. Generation of in-memory message tables is specified by the incatalog flag in the sams file in which the message text is defined (see SAMS for more information on sams files). If the messages have been generated at compile time with this option specified, the dce_msg_define_msg_table() routine can be called by the application to register an in-memory table containing the messages. The table parameter to the call should identify a message table structure defined in a header file generated by sams during compilation (see the EXAMPLES section). The count parameter specifies the number of elements contained in the table. If an error is detected during the call, the routine will return an appropriate error code in the status parameter. EXAMPLES The following code fragment shows how an application (whose serviceability component name is app) would set up an in-memory message table: #include #include #include #include "dceappmsg.h" /* defines app_msg_table */ error_status_t status; The following call adds the message table to the in-memory table. Note that you must include . You also have to link in dceappmsg.obj and dceappsvc.obj (object files produced by compiling sams-generated .c files), which contain the code for the messages and the table, respectively. dce_msg_define_msg_table( app_msg_table, sizeof(app_msg_table) / sizeof(app_msg_table[0]), &status ); ERROR CODES See dce_msg_get. RELATED INFORMATION Functions: dce_msg_get dce_msg_get_msg dce_msg_get_default_msg 4 dce_msg_get NAME dce_msg_get - Retrieves text of specified DCE message SYNOPSIS #include unsigned char *dce_msg_get( unsigned32 message ); PARAMETERS Input message ID of message to be retrieved. DESCRIPTION The dce_msg_get() routine is a convenience'' form of the dce_msg_get_msg() routine. Like dce_msg_get_msg(), dce_msg_get() retrieves the text for a specified message (which is a 32-bit DCE message ID as described in dce_msg_intro). However, dce_msg_get() does not return a status code; it either returns the specified message successfully or fails (aborts the program) with an assertion error if the message could not be found or memory could not be allocated. The routine implicitly determines the correct message catalog in which to access the specified message, and opens it; the caller only has to call this routine. The routine first searches the appropriate message catalog for the message, and then (if it cannot find the catalog) searches the in- memory message table, if it exists. The message, if found, is returned in allocated space to which the routine returns a pointer. The pointed-to space must be freed by the caller using free. ERROR CODES msg_s_bad_id Invalid message ID A message ID with an invalid technology or component was specified. msg_s_no_cat_open Could not open the message catalog for the specified message ID. msg_s_no_cat_perm Local file permissions prevented the program from opening the message catalog for the specified message ID. msg_s_no_catalog The message catalog for the specified message ID does not exist. msg_s_no_default Could not find the default message for the specified status code in the internal tables. msg_s_no_memory Could not allocate memory for message table, string copy, or other internal requirement. msg_s_not_found Could not find the text for the specified status code in either the in-core message tables or the message catalogs. msg_s_ok_text The operation was performed successfully. RELATED INFORMATION Functions: dce_msg_define_msg_table dce_msg_get_msg dce_msg_get_default_msg 4 dce_msg_get_cat_msg NAME dce_msg_get_cat_msg - Opens message catalog and retrieves message SYNOPSIS #include unsigned char *dce_msg_get_cat_msg( unsigned32 message, error_status_t *status ); PARAMETERS Input message ID of message to be retrieved. Output status Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. DESCRIPTION The dce_msg_get_cat_msg() routine is a "convenience" form of the dce_msg_cat_get_msg() routine. The difference between it and the latter routine is that dce_msg_get_cat_msg() does not require the message catalog to be explicitly opened; it determines the correct catalog from the message parameter (which is a 32-bit DCE message ID as described in dce_error_inq_text), opens it, retrieves the message, and returns a pointer to malloc()'d space containing the message. If the message catalog is inaccessible, the routine returns an error. (See the routine dce_msg_get() for a description of the return value.) The routine will fail if the message catalog is not correctly installed. ERROR CODES See dce_msg_get. RELATED INFORMATION Functions: dce_msg_cat_close dce_msg_cat_get_msg dce_msg_cat_open dce_msg_get dce_msg_get_msg 4 dce_msg_get_default_msg NAME dce_msg_get_default_msg - Retrieves DCE message from in-memory tables SYNOPSIS #include unsigned char *dce_msg_get_default_msg( unsigned32 message, error_status_t *status ); PARAMETERS Input message ID of message to be retrieved. Output status Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. DESCRIPTION The dce_msg_get_default_msg() routine retrieves a message from the application's in-memory tables. It returns a pointer to static space that should not be freed. If the specified message (which is a 32-bit DCE message ID as described in dce_error_inq_text) cannot be found in the in-memory tables, the routine returns NULL and fills in status with the appropriate error code. This routine should be used only for message strings that will never have to be translated (see dce_msg_translate_table). All messages for a given component are stored in a single message catalog generated by the sams utility when the component is built. Messages may also be compiled directly into the component code, thus rendering the successful retrieval of message text independent of whether or not the message catalogs were correctly installed. Generation of in-memory message tables is specified by the incatalog flag in the sams file in which the message text is defined. (See sams for more information on sams files.) If the messages have been generated at compile time with this option specified, the dce_msg_define_msg_table() routine can be called by the application to set up an in-memory table containing the messages. EXAMPLES The following code fragment shows how dce_msg_get_default_msg() might be called to retrieve the in-memory copy of a message defined by a DCE application (whose serviceability component name is app): #include #include #include #include "dceappmsg.h" /* "test_msg" is defined in this file */ unsigned char *my_msg; error_status_t status; <. . .> my_msg = dce_msg_get_default_msg(test_msg, &status); printf("Message is: %s\n", my_msg); ERROR CODES See dce_msg_get. RELATED INFORMATION Functions: dce_msg_define_msg_table dce_msg_get dce_msg_get_msg 4 dce_msg_get_msg NAME dce_msg_get_msg - Retrieve a DCE message from its ID SYNOPSIS #include unsigned char *dce_msg_get_msg( unsigned32 message, error_status_t *status ); PARAMETERS Input message ID of message to be retrieved. Output status Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. DESCRIPTION The dce_msg_get_msg() routine retrieves the text for a specified message (which is a 32-bit DCE message ID as described in dce_error_inq_text). The routine implicitly determines the correct message catalog in which to access the message, and opens it; the caller only has to call the routine. The routine first searches the appropriate message catalog for the message, and then (if it cannot find the catalog) searches the in- memory message table. If the message cannot be found in either of these places, the routine returns a default string and fills in status with an error code. This routine thus always returns a string, even if there is an error (except for msg_s_no_memory). The message, if found, is returned in allocated space to which the routine returns a pointer. The pointed-to space must be freed by the caller using free. If memory cannot be allocated, the routine returns NULL and fills in status with the msg_s_no_memory error code. ERROR CODES See dce_msg_get. RELATED INFORMATION Functions: dce_msg_define_msg_table dce_msg_get dce_msg_get_default_msg 4 dce_msg_translate_table NAME dce_msg_translate_table - Translates all in-memory messages in a table SYNOPSIS #include void dce_msg_translate_table( dce_msg_table_t *table, unsigned32 count, error_status_t *status ); PARAMETERS Input table A message table structure (defined in a header file generated by sams during compilation (see "EXAMPLES" below), the contents of which are to be translated. count The number of elements contained in the table. Output status Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. DESCRIPTION The dce_msg_translate_table() routine overwrites the specified in-memory message table (that is, updates the in-memory table with the contents of a message table, which has changed for some reason; for example, because of a change in locale). If any in-memory message is not found in the message catalog, all in-memory messages are left unchanged. EXAMPLES The following code fragment shows how dce_msg_translate_table() might be called (in an application whose serviceability component name is app) to translate a DCE application's in-memory message table, set up by an earlier call to dce_msg_define_msg_table(): #include #include #include #include "dceappmsg.h" char *loc_return; error_status_t status; <. . .> dce_msg_translate_table (app_msg_table, sizeof(app_msg_table) / sizeof(app_msg_table[0]), &status ); ERROR CODES See dce_msg_get. RELATED INFORMATION Functions: dce_msg_define_msg_table 4 dce_pgm_printf NAME dce_pgm_printf dce_pgm_fprintf dce_pgm_sprintf - Formatted DCE message output routines SYNOPSIS #include int dce_pgm_printf( unsigned32 messageid, . . . ); int dce_pgm_fprintf( FILE *stream, unsigned32 messageid, . . . ); unsigned char *dce_pgm_sprintf( unsigned32 messageid, . . . ); PARAMETERS Input messageid The message ID, defined in the message's code field in the sams file. stream An open file pointer. . . . Any format arguments for the message string. DESCRIPTION The dce_pgm_printf() routine is equivalent to dce_printf(), except that it prefixes the program name to the message (in the standard style of DCE error messages), and appends a newline to the end of the message. The routine dce_printf() does neither. This allows clients (which do not usually use the serviceability interface) to produce error (or other) messages which automatically include the originating application's name. Note that the application should call dce_svc_set_progname() first to set the desired application name. Otherwise, the default program name will be PID#nnnn, where nnnn is the process ID of the application making the call. The dce_pgm_sprintf() routine is similarly equivalent to dce_sprintf(), and the dce_pgm_fprintf() routine is similarly equivalent to dce_fprintf(). ERROR CODES See dce_msg_get. RELATED INFORMATION Functions: dce_fprintf dce_msg_get_msg dce_printf dce_sprintf dce_svc_set_progname 4 dce_printf NAME dce_printf dce_fprintf dce_sprintf - Formatted DCE message output routines SYNOPSIS #include int dce_printf( unsigned32 messageid, . . . ); int dce_fprintf( FILE *stream, unsigned32 messageid, . . . ); unsigned char *dce_sprintf( unsigned32 messageid, . . . ); PARAMETERS Input messageid The message ID, defined in the message's code field in the sams file. stream An open file pointer. . . . Any format arguments for the message string. DESCRIPTION The dce_printf() routine retrieves the message text associated with the specified messageid, and prints the message and its arguments on the standard output. The routine determines the correct message catalog and, if necessary, opens it. If the message catalog is inaccessible, and the message exists in an in-memory table, then this message is printed. If neither the catalog nor the default message is available, a default message is printed. The dce_fprintf() routine functions much like dce_printf(), except that it prints the message and its arguments on the specified stream. The dce_sprintf() routine retrieves the message text associated with the specified messageid, and prints the message and its arguments into an allocated string that is returned. The routine determines the correct message catalog and, if necessary, opens it. If the message catalog is inaccessible, and the message exists in an in-memory table, then this message is printed. If neither the catalog nor the default message is available, a default message is printed. The dce_pgm_printf() routine is equivalent to dce_printf(), except that it prefixes the program name to the message (in the standard style of DCE error messages), and appends a newline to the end of the message. For more information, see the dce_pgm_printf reference page. EXAMPLES Assume that the following message is defined in an application's sams file: start code arg_msg text "This message has exactly %d, not %d argument(s)" action "None required" explanation "Test message with format arguments" end The following code fragment shows how dce_sprintf() might be called to write the message (with some argument values) into a string: unsigned char *my_msg; my_msg = dce_sprintf(arg_msg, 2, 8); puts(my_msg); free(my_msg); Of course, dce_printf() could also be called to print the message and arguments: dce_printf(arg_msg, 2, 8); ERROR CODES See dce_msg_get. NOTES The final formatted string generated by dce_sprintf() must not exceed 1024 bytes. RELATED INFORMATION Functions: dce_msg_get_msg dce_svc_set_progname 3 dce_server_intro NAME dce_server_intro - Introduction to the DCE server routines DESCRIPTION The routines described on this reference page are used by servers to register themselves with DCE. This includes registering with the RPC runtime, the local endpoint mapper, and the namespace. Routines are also available to set up DCE security so that servers can receive and invoke authenticated RPCs. THE DCE SERVER ROUTINES The server routines are as follows, listed in alphabetical order: dce_server_disable_service() Unregisters an individual interface of a DCE server from the RPC runtime, and marks the server's endpoints as disabled in the dced's endpoint mapper service. dce_server_enable_service() Registers an individual interface (application service) of a DCE server with the RPC runtime, and marks the server's endpoints as enabled in the dced's endpoint mapper service. dce_server_inq_attr() Obtains application-specific attribute data from the dced server configuration data. dce_server_inq_server() Obtains the server configuration data dced used to start the server. dce_server_inq_uuids() Obtains the UUIDs that dced used in its srvrconf and srvrexec facilities to identify the server's configuration and execution data. dce_server_register() Registers a DCE server by establishing a server's binding information, registering its services (represented by interface IDs) with the RPC runtime, and entering its endpoints in the dced's endpoint mapper service. dce_server_sec_begin() Prepares a server to receive and generate authenticated RPCs. dce_server_sec_done() Releases the resources previously set up by a call to dce_server_sec_begin(). dce_server_unregister() Unregisters a DCE server by unregistering a servers services (interfaces) from the RPC runtime, and removing the server's endpoints from the dced's endpoint mapper service. dce_server_use_protseq() Registers a protocol sequence to use for the server. DATA TYPES AND STRUCTURES dce_server_handle_t An opaque data structure containing information the runtime uses to establish the server with DCE. dce_server_register_data_t A structure that contains an interface handle (generated by IDL), a default EPV, and a count and array of dce_server_type_ts for services that use RPC object types. dce_server_type_t A structure containing a manager type UUID and an RPC entry-point vector (EPV) that specified which routines implement the IDL interface for the specific type. server_t See dced_intro for a complete description of server_t. FILES dce/dced.h dce/dced_base.idl RELATED INFORMATION BOOKS: OSF DCE Application Development Guide 4 dce_server_disable_service NAME dce_server_disable_service - Disables an individual service of a server SYNOPSIS #include void dce_server_disable_service( dce_server_handle_t server_handle, rpc_if_handle_t interface, error_status_t *status ); PARAMETERS Input server_handle An opaque handle returned by dce_server_register(). interface Specifies an opaque variable containing information the runtime uses to access interface specification data. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully. The only status code is error_status_ok. DESCRIPTION The dce_server_disable_service() routine disables an individual service that a server provides by unregistering the service's interface from the RPC runtime and marking the server's endpoints as disabled in the local dced's endpoint mapper service. For dced to recognize all of a server's services, a server should register all its application services using the dce_server_register() routine. If it later becomes necessary for the server to disable an interface, it can use the dce_server_disable_service() routine rather than unregistering the entire server. RELATED INFORMATION Routines: rpc_intro dce_server_enable_service dce_server_register Books: OSF DCE Application Development Guide 4 dce_server_enable_service NAME dce_server_enable_service - Enables an individual service for a server SYNOPSIS #include void dce_server_enable_service( dce_server_handle_t server_handle, rpc_if_handle_t interface, error_status_t *status ); PARAMETERS Input server_handle An opaque handle returned by dce_server_register(). interface Specifies an opaque variable containing information the runtime uses to access interface specification data. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully. The only status code is error_status_ok. DESCRIPTION The dce_server_enable_service() routine enables an individual service that a server provides by registering the service's interface with the RPC runtime, and registering the endpoints in the endpoint map. If the dce_server_c_no_endpoints flag was set with the dce_server_register() call prior to callibng this routine, the endpoints are not registered in the endpoint map. A server commonly registers all its services with DCE at once by using the dce_server_register() routine. If necessary, a server can use the dce_server_disable_service() routine to disable individual services and then reenable them by using dce_server_enable_service(). However, suppose a server needs its services registered in a certain order, or it require application- specific activities between the registration of services. If a server requires this kind of control as services are registered, you can set the server->services.list[i].flags field of the server_t structure to service_c_disabled for individual services prior to calling dce_server_register(). Then, the server can call dce_server_enable_service() for each service when needed. RELATED INFORMATION Routines: dce_server_disable_service dce_server_register Books: OSF DCE Application Development Guide 4 dce_server_inq_attr NAME dce_server_inq_attr - Obtains from dced the value of an attribute known to the server SYNOPSIS #include void dce_server_inq_attr( uuid_t *attribute_uuid, sec_attr_t *value, error_status_t *status ); PARAMETERS Input attribute_uuid The UUID dced uses to identify an attribute. Output value Returns the attribute. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok dced_s_server_attr_not_found dced_s_not_started_by_dced DESCRIPTION The dce_server_inq_attr() routine obtains an attribute from the environment created by dced when it started the server. Each server maintains among other things, a list of attributes that are used to describe application-specific behavior. RELATED INFORMATION Routines: sec_intro dced_intro dce_server_inq_uuids dce_server_inq_server Books: OSF DCE Application Development Guide 4 dce_server_inq_server NAME dce_server_inq_server - Obtains the server configuration data dced used to start the server SYNOPSIS #include void dce_server_inq_server( server_t **server, error_status_t *status ); PARAMETERS Output server Returns the structure that describes the server's configuration. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok dced_s_not_started_by_dced dced_s_data_unavailable DESCRIPTION The dce_server_inq_server() routine obtains the server configuration data (srvrconf) maintained by dced and used by dced to start the server. This routine is commonly called prior to registering the server to obtain the server data used as input to dce_server_register(). RELATED INFORMATION Routines: dced_intro dce_server_register Books: OSF DCE Application Development Guide 4 dce_server_inq_uuids NAME dce_server_inq_uuids - Obtains the UUIDs that dced associates with the server's configuration and execution data SYNOPSIS #include void dce_server_inq_uuids( uuid_t *conf_uuid, uuid_t *exec_uuid, error_status_t *status ); PARAMETERS Output conf_uuid Returns the UUID that dced uses to identify the server's configuration data. If a NULL value is input, no value is returned. exec_uuid Returns the UUID that dced uses to identify the executing server. If a NULL value is input, no value is returned. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok dced_s_not_started_by_dced DESCRIPTION The dce_server_inq_uuids() routine obtains the UUIDs that dced uses in its srvrconf and srvrexec services to identify the server's configuration and execution data. The server can then use dced API routines to access the data and perform other server management functions. RELATED INFORMATION Routines: dced_intro dce_server_inq_server dced_API Books: OSF DCE Application Development Guide 4 dce_server_register NAME dce_server_register - Registers a server with DCE SYNOPSIS #include void dce_server_register( unsigned32 flags, server_t *server, dce_server_register_data_t *data, dce_server_handle_t *server_handle, error_status_t *status ); PARAMETERS Input flags Specifies options for server registration. Combinations of the following values may be used: dce_server_c_no_protseqs dce_server_c_no_endpoints dce_server_c_ns_export server Specifies the server data, commonly obtained from dced by calling dce_server_inq_server(). The server_t structure is described in sec_intro. data Specifies the array of data structures that contain the additional information required for the server to service requests for specific remote procedures. Each structure of the array includes: + An interface handle (ifhandle) of type rpc_if_handle_t + An entry point vector (epv) of type rpc_mgr_epv_t + A number (num_types) of type unsigned32 representing the number in the following array + An array of server types (types) of type dce_server_type_t The dce_server_type_t structure contains a UUID (type) of type uuid_t representing the object type, and a manager entry point vector (epv) of type rpc_mgr_epv_t representing the set of procedures implemented for the object type. Output server_handle Returns a server handle, which is a pointer to an opaque data structure containing information about the server. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok rpc_s_no_memory DESCRIPTION By default, the dce_server_register() routine registers a DCE server by establishing a server's binding information for all valid protocol sequences, registering all the servers services with the RPC runtime, and entering the server's endpoints in dced's endpoint mapper service. Prior to calling the dce_server_register() routine, the server obtains the server configuration data from dced by calling dce_server_inq_server(). The server must also set up an array of registration data, where the size of the array represents all the server's services that are currently registered in the server configuration data of dced. (server->services.count). If the memory for the array is dynamically allocated, it must not be freed until after the corresponding dce_server_unregister() routine is called. You can modify the behavior of dce_server_register() Depending on the values of the flags parameter. If the flag has the value dce_server_c_ns_export, the the binding information is also exported to the namespace. The namespace entry is determined for each service by the server->services.list[i].entryname parameter. If this parameter has no value, the default value for the entire server is used (server->entryname). If the flag has the value dce_server_c_no_endpoints, the binding information is not registered with the endpoint map. Your application can use rpc_ep_register() to register specific binding information. If the flag has the value dce_server_c_no_protseqs, specific protocol sequences are used rather than all valid protocol sequences. Use of this flag requires that the server first call dce_server_use_protseq() at least once for a valid protocol sequence. RELATED INFORMATION Routines: dced_intro dce_server_inq_server dce_server_unregister rpc_server_listen dce_server_sec_begin Books: OSF DCE Application Development Guide 4 dce_server_sec_begin NAME dce_server_sec_begin - Establishes a server to receive fully authenticated remote procedure calls (RPCs) and to also act as a client to do authenti- cated RPCs SYNOPSIS #include void dce_server_sec_begin( unsigned32 flags, error_status_t *status ); PARAMETERS Input flags Flags are set to manage keys and setup a login context. Valid values include the following: dce_server_c_manage_key dce_server_c_login Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok dced_s_need_one_server_prin dced_s_not_started_by_dced dced_s_no_server_keyfile dced_s_cannot_create_key_mgmt_thr dced_s_cannot_detach_key_mgmt_thr DESCRIPTION The dce_server_sec_begin() routine prepares a server to receive authenticated RPCs. It also sets up all that is required for the application, when behaving as a client to other servers, to do authenticated RPCs as a client. When authentication is required, this call must preceed all other RPC and DCE server initialization calls, including dce_server_register(). When your application is finished listening for RPCs, it should call the dce_server_sec_done() routine. RELATED INFORMATION Routines: dce_server_register rpc_server_listen dce_server_sec_done Books: OSF DCE Application Development Guide 4 dce_server_sec_done NAME dce_server_sec_done - Releases resources established for a server to receive (and when acting as a client, to send) fully authenticated remote procedure calls (RPCs) SYNOPSIS #include void dce_server_sec_done( error_status_t *status ); PARAMETERS Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully. The only status code is error_status_ok. DESCRIPTION The dce_server_sec_done() routine releases the resources previously set up by a call to dce_server_sec_begin(). The dce_server_sec_begin() routine sets all that is needed for a server to receive authenticated RPCs and it also sets up all that is required for the application to do authenticated RPCs as a client. If this routine is used, it must follow all other server DCE and RPC initialization and cleanup calls. RELATED INFORMATION Routines: dce_server_sec_begin rpc_server_listen Books: OSF DCE Application Development Guide 4 dce_server_unregister NAME dce_server_unregister - Unregisters a DCE server SYNOPSIS #include void dce_server_unregister( dce_server_handle_t *server_handle, error_status_t *status ); PARAMETERS Input server_handle An opaque handle returned by dce_server_register(). Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully. The only status code is error_status_ok. DESCRIPTION The dce_server_unregister() routine unregisters a DCE server by unregistering a servers services (interfaces) from the RPC runtime. When a server has stopped listening for remote procedure calls, it should call this routine. The flags set with the corresponding dce_server_register() routine are part of the server handle's information used to determine what action to take or not take. These actions include removing the server's endpoints from the dced's endpoint mapper service and unexporting binding information from the namespace. Use the dce_server_disable_service() routine to disable specific application services rather than unregistering the whole server. RELATED INFORMATION Routines: dce_server_register rpc_server_listen dce_server_disable_service Books: OSF DCE Application Development Guide 4 dce_server_use_protseq NAME dce_server_use_protseq - Tells DCE to use the specified protocol sequence for receiving remote procedure calls Used by server applications. SYNOPSIS #include void dce_server_use_protseq( dce_server_handle_t server_handle, unsigned char *protseq, error_status_t *status ); PARAMETERS Input server_handle An opaque handle. Use the value of NULL. protseq Specifies a string identifier for the protocol sequence to register with the RPC runtime. (For a list of string identifiers, see the table of valid protocol sequences in the rpc_intro reference page.) Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully. The only status code is error_status_ok. DESCRIPTION The dce_server_use_protseq() routine registers an individual protocol sequence with DCE. Typical servers use all valid protocol sequences, the default behavior for the dce_server_register() call, and so most servers do not need to call this dce_server_use_protseq() routine. However, this routine may be called prior to dce_server_register(), to restrict the protocol sequences used. A server must register at least one protocol sequence with the RPC runtime to receive remote procedure call requests. A server can call this routine multiple times to register additional protocol sequences. RELATED INFORMATION Routines: rpc_intro dce_server_register rpc_server_use_protseq Books: OSF DCE Application Development Guide 3 dce_svc_intro NAME dce_svc_intro - Introduction to the DCE serviceability interface DESCRIPTION The routines listed below are intended to be used by servers that export the serviceability interface defined in service.idl. The complete list of these remote serviceability implementation calls is as follows (the remote operation name is given in the left column, and the corresponding implementation routine is given in the right column). dce_svc_set_route dce_svc_routing dce_svc_set_dbg_route dce_svc_debug_routing dce_svc_set_dbg_levels dce_svc_debug_set_levels dce_svc_inq_components dce_svc_components dce_svc_inq_table dce_svc_table dce_svc_filter_control dce_svc_filter dce_svc_inq_stats dce_svc_inq_stats These routines perform all the necessary processing (except for checking clients' authorization) that must be done by the application manager to implement the remote serviceability operations. Note that most of these routines have little meaning except as implementations of remote operations. However, the dce_svc_routing(), dce_svc_filter(), dce_svc_debug_routing() and dce_svc_debug_set_levels() routines can conceivably be used by servers as purely local operations (for example, in order to allow routing and debug levels to be set via command line flags when the server is invoked). The dce_svc_log_ routines provide read access to BINFILE format logs which are created and written by the DCE serviceability routines; see svcroute for further information. The dce_svc_log_handle_t typedef is an opaque pointer to a handle for an opened logfile. Applications that use the serviceability interface can install a routine that will be effectively "hooked" into the operation of the interface. If a filter is installed, it will be called whenever one of the serviceability output routines (dce_svc_printf()) is about to output a message; whenever this happens, the filter will receive a group of parameters that describe the message that is about to be output and the circumstances that provoked the action. The filter can then allow the message output to proceed, or suppress the message. Along with the filter routine itself, the application also installs a filter control routine, whose purpose is to permit the behavior of the filter to be altered dynamically while the application is running. The dce_svc_filter() routine is the interface's call-in to such an installed filter control. THE DCE SERVICEABILITY ROUTINES The serviceability routines are as follows, listed in alphabetical order: dce_assert() Adds runtime "can't happen" assertions to programs (such as, programming errors). dce_svc_components() Returns an array containing the names of all components in the program that have been registered with the dce_svc_register() routine. dce_svc_debug_routing() Specifies both the level of an applications's serviceability debug messaging, and where the messages are routed. dce_svc_debug_set_levels() Sets serviceability debugging message level(s) for a component. dce_svc_define_filter() Lets applications define serviceability filtering routines. dce_svc_filter() Controls the behavior of the serviceability message filtering routine, if one exists. dce_svc_log_close() Closes an open binary format serviceability log and releases all internal state associated with the handle. dce_svc_log_get() Reads the next entry from a binary format serviceability log. dce_svc_log_open() Opens the specified file for reading. dce_svc_log_rewind() Rewinds the current reading position of the specified (by handle) logfile to the first record. dce_svc_printf() Provides the normal call for writing or displaying serviceability messages. dce_svc_register() Registers a serviceability handle and sub- component table. dce_svc_routing() Specifies how normal (non-debug) serviceability messages are routed. dce_svc_set_progname() If not called, the application's generated serviceability messages will be identified by its process ID. dce_svc_table() Returns the serviceability subcomponent table registered with the specified component. dce_svc_unregister() Destroys a serviceability handle, releasing all allocated resources associated with the handle. DATA TYPES AND STRUCTURES dce_svc_filter_proc_t The prototype of a serviceability filtering routine. dce_svc_filterctl_proc_t The prototype of a serviceability filter-control routine. dce_svc_handle_t An opaque handle to generate serviceability messages. (Use dce_svc_register() or DCE_DEFINE_SVC_HANDLE to obtain one.) dce_svc_log_handle_t An opaque handle to an open serviceability binary format log file. (Use dce_svc_log_open() to obtain one.) dce_svc_log_prolog_t A structure containing data about a serviceability binary format log entry. dce_svc_prolog_t A structure containing the initial message parameters passed to the filtering routine. FILES dce/service.idl dce/dce_svc.h RELATED INFORMATION BOOKS: OSF DCE Application Development Guide 4 dce_assert NAME dce_assert - Inserts program diagnostics SYNOPSIS #define DCE_ASSERT #include void dce_assert( dce_svc_handle_t handle, int expression ); PARAMETERS Input handle A registered serviceability handle. expression An expression the truth of which is to be tested. DESCRIPTION The dce_assert macro is used to add runtime "can't happen" assertions to programs (that is, programming errors). On execution, when expression evaluates to 0 (that is, to "false"), then dce_svc_printf() is called with parameters to generate a message identifying the expression, source file and line number. The message is generated with a severity level of svc_c_sev_fatal, with the svc_c_action_abort flag specified (which will cause the program to abort when the assertion fails and the message is generated). See the dce_svc_register reference page for more information. The handle parameter should be a registered serviceability handle; it can also be NULL, in which case an internal serviceability handle will be used. Assertion-checking can be enabled or disabled at compile time. The header file dce/assert.h can be included multiple times. If DCE_ASSERT is defined before the header is included, assertion checking is performed. If it is not so defined, then the assertion-checking code is not compiled in. The system default is set in dce/dce.h. ERROR CODES See dce_svc_register. RELATED INFORMATION Functions: dce_svc_register 4 dce_svc_components NAME dce_svc_components - DCE serviceability routine that returns registered component names SYNOPSIS #include #include void dce_svc_components( dce_svc_stringarray_t *table, error_status_t *status ); PARAMETERS Output table An array containing the names of all components that have been registered with the dce_svc_register() routine. status Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. DESCRIPTION The dce_svc_components routine returns an array containing the names of all components in the program that have been registered with the dce_svc_register() routine. EXAMPLES The following code fragment shows how the dce_svc_components() routine should be used in a DCE application's implementation of the serviceability remote interface. The function defined below is the implementation of the app_svc_inq_components operation defined in the application's serviceability .epv file. Clients call this function remotely, and the function, when called, first checks the caller's authorization and then (if the client is authorized to perform the operation) calls the dce_svc_components() routine to perform the actual operation. /***** * * app_svc_inq_components -- remote request for list of all * components registered by * dce_svc_register(). * *****/ static void app_svc_inq_components( handle_t h, dce_svc_stringarray_t *table, error_status_t *st ) { int ret; /* Check the client's permissions here; if they are insufficient, */ /* deny the request. Otherwise, proceed with the operation... */ dce_svc_components(table, st); } ERROR CODES See dce_svc_register. FILES dce/service.idl 4 dce_svc_debug_routing NAME dce_svc_debug_routing - Specifies how debugging messages are routed SYNOPSIS #include #include void dce_svc_debug_routing( unsigned char *where, error_status_t *status ); PARAMETERS Input where A four-field routing string, the format of which is described in svcroute. Output status Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. DESCRIPTION The dce_svc_debug_routing() routine specifies both the level of an applications's serviceability debug messaging, and where the messages are routed. The where parameter is a four-field routing string, as described in svcroute. All four fields are required. The routine is used to specify the disposition of serviceability debug messages. If called before the component is registered (with dce_svc_register()), the disposition is stored until it is needed. In case of error, the status parameter is filled in with an error code. To set only the debugging level for a component, use the dce_svc_debug_set_levels() routine. ERROR CODES See dce_svc_register. RELATED INFORMATION Functions: dce_svc_debug_set_levels. Files: svcroute 4 dce_svc_debug_set_levels NAME dce_svc_debug_set_levels - Sets the debugging level for a component SYNOPSIS #include #include void dce_svc_debug_set_levels( unsigned char *where, error_status_t *status ); PARAMETERS Input where A multi-field string consisting of the component name separated by a colon from a comma-separated list of subcomponent/level pairs, as described in svcroute. Output status Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. DESCRIPTION The dce_svc_debug_set_levels() routine sets serviceability debugging message level(s) for a component. The where parameter is a multi-field string consisting of the component name separated by a colon from a comma-separated list of subcomponent/level pairs, as described in svcroute. The subcomponents are specified by codes defined in the component's sams file; the levels are specified by single digits (1 through 9). If the routine is called before the component is registered (with dce_svc_register()), the disposition is stored until it is needed. In case of error, the status parameter is filled in with an error code. To set both the debug level and routing for a component, use the dce_svc_debug_routing() routine. ERROR CODES See dce_svc_register. RELATED INFORMATION Functions: dce_svc_debug_routing Files: svcroute 4 dce_svc_define_filter NAME dce_svc_define_filter - DCE serviceability filtering routines SYNOPSIS #include #include #include #include void dce_svc_define_filter( dce_svc_handle_t handle, dce_svc_filter_proc_t filter_function, dce_svc_filterctl_proc_t filter_ctl_function, error_status_t *status ); DESCRIPTION The serviceability interface provides a hook'' into the message-output mechanism that allows applications to decide at the time of messaging whether the given message should be output or not. The application defines its own routine to perform whatever checking is desired, and installs the routine (the filter_function parameter) with a call to dce_svc_define_filter(). The filter routine to be installed must have the signature defined by the dce_svc_filter_proc_t typedef. Once installed, the routine will be automatically invoked every time a serviceability routine is called to output a message. The filter receives a prolog argument which contains all the pertinent information about the message. If the filter returns TRUE, the message is output per the original serviceability call. If the filter returns FALSE, the message is not output. The information in the prolog allows such decisions to be made on the basis of severity level, subcomponent, message index, and so on. For details, see the header file dce/svcfilter.h. In addition, an application that installs a message-filtering routine must also define a routine that can be called remotely to alter the operation of the filter routine. This procedure must have the signature defined by the dce_svc_filterctl_proc_t typedef. The routine will be invoked with an opaque byte array parameter (and its length), which it is free to interpret in an appropriate manner. The remote-control routine is installed by the same call to dce_svc_define_filter() (as the filter_ctl_function parameter) in which the filter itself is installed. See dce_svc_filter. EXAMPLES The following code fragment consists of example versions of an application's routines to: filter serviceability messages; alter the behavior of the filter routine; install the two routines. /***** * Filter routine-- this is the routine that's hooked into the * serviceability mechanism when you install it by * calling dce_svc_define_filter(). *****/ boolean app_filter(prolog, args) dce_svc_prolog_t prolog; va_list args; { if (filter_setting) { printf("The value of filter_setting is TRUE\n"); printf("The progname is %s\n", prolog->progname); if (prolog->attributes & svc_c_sev_notice) printf("This is a Notice-type message\n"); switch (prolog->table_index) { case app_s_server: printf("Server sub-component\n"); break; case app_s_refmon: printf("Refmon sub-component\n"); break; case app_s_manager: printf("Manager sub-component\n"); break; } } return 1; } /***** * Filter Control routine-- this is the entry point for the remote- * control call to modify the filter * routine's behavior. *****/ void app_filter_control(arg_size, arg, status) idl_long_int arg_size; idl_byte *arg; error_status_t *status; { if (strncmp(arg, "Toggle", arg_size) != 0) return; else { filter_setting = (filter_setting == FALSE) ? TRUE : FALSE; if (filter_setting) printf(" FILTER IS TURNED ON\n"); else printf(" FILTER IS TURNED OFF\n"); } return; } /***** * install_filters-- calls dce_svc_define_filter() to install the * above 2 routines. *****/ void install_filters() { unsigned32 status; filter_setting = TRUE; dce_svc_define_filter(app_svc_handle, app_filter, dce_svc_filterctl_proc_t)app_filter_control, &status); } ERROR CODES See dce_svc_register. RELATED INFORMATION Functions: dce_svc_register DCE_SVC_DEFINE_HANDLE 4 dce_svc_filter NAME dce_svc_filter - Controls behavior of serviceability filter SYNOPSIS #include #include void dce_svc_filter( dce_svc_string_t component, idl_long_int arg_size, idl_byte *argument, error_status_t *status ); PARAMETERS Input component The name of the serviceability-registered component, defined in the component field of the sams file. arg_size The number of characters contained in argument. argument A string value to be interpreted by the target component's filter control routine. Output status Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. DESCRIPTION The dce_svc_filter() routine controls the behavior of the serviceability message filtering routine, if one exists. Along with the filter routine itself, the application also installs a filter control routine, whose purpose is to permit the behavior of the filter to be altered dynamically while the application is running. The dce_svc_filter() routine is the interface's call-in to such an installed filter control. If an application has installed a serviceability filtering routine, and if filter remote control is desired, the application's filter routine (installed by the call to dce_svc_define_filter()) should be coded so that its operation can be switched to the various desired alternatives by the values of static variables to which it has access. These variables should also be accessible to the filter control routine. The filter control routine thus receives from dce_svc_filter() an argument string (which it uses to set the variables), the meaning of whose contents are entirely application- defined. ERROR CODES See dce_svc_register. FILES dce/service.idl 4 dce_svc_log_close NAME dce_svc_log_close - Closes an open logfile SYNOPSIS #include #include #include void dce_svc_log_close( dce_svc_log_handle_t handle, error_status_t *status ); PARAMETERS Input handle The handle (returned by dce_svc_log_open()) of the logfile to be closed. Output status Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. DESCRIPTION The dce_svc_log_close() routine closes an open binary format serviceability log and releases all internal state associated with the handle. ERROR CODES See dce_svc_register. RELATED INFORMATION Functions: dce_svc_log_get dce_svc_log_open dce_svc_log_rewind 4 dce_svc_log_get NAME dce_svc_log_get - Reads the next record from a binary logfile SYNOPSIS #include #include #include void dce_svc_log_get( dce_svc_log_handle_t handle, dce_svc_log_prolog_t *prolog, error_status_t *status ); PARAMETERS Input handle The handle (returned by dce_svc_log_open()) of the logfile to be read. Output prolog A pointer to a structure containing information read from the logfile record. status Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. DESCRIPTION The dce_svc_log_get() routine reads the next entry from a binary format serviceability log, and fills in prolog with a pointer to a private data area containing the data read. The contents of the prolog structure are defined in dce/svclog.h. ERROR CODES See dce_svc_register. RELATED INFORMATION Functions: dce_svc_log_close dce_svc_log_open dce_svc_log_rewind 4 dce_svc_log_open NAME dce_svc_log_open - Opens binary log file SYNOPSIS #include #include #include void dce_svc_log_open( const char *name, dce_svc_log_handle_t *handle, error_status_t *status ); PARAMETERS Input name The pathname of the logfile to be opened. Output handle A filled-in handle to the opened logfile specified by name. status Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. DESCRIPTION The dce_svc_log_open() routine opens the binary log file specified by name for reading. If the call is successful, handle is filled in with a handle to be used with the other dce_svc_log_ calls. On error, status will contain an error code. ERROR CODES See dce_svc_register. RELATED INFORMATION Functions: dce_svc_log_close dce_svc_log_get dce_svc_log_rewind 4 dce_svc_log_rewind NAME dce_svc_log_rewind - Rewinds binary logfile to first record SYNOPSIS #include #include #include void dce_svc_log_rewind( dce_svc_log_handle_t handle, error_status_t *status ); PARAMETERS Input handle The handle (returned by dce_svc_log_open()) of the logfile to be rewound. Output status Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. DESCRIPTION The dce_svc_log_rewind() routine rewinds the current reading position of the specified (by handle) binary logfile to the first record. ERROR CODES See dce_svc_register. RELATED INFORMATION Functions: dce_svc_log_close dce_svc_log_get dce_svc_log_open 4 dce_svc_printf NAME dce_svc_printf - Generates a serviceability message SYNOPSIS #include void dce_svc_printf( DCE_SVC(dce_svc_handle_t handle, char * argtypes), const unsigned32 table_index, const unsigned32 attributes, const unsigned32 messageID, . . . ); PARAMETERS Input handle The caller's serviceability handle. argtypes Format string for the message. table_index The message's sub-component name (defined in the sams file). attributes Any routing, severity, action, or debug attributes that are to associated with the generated message, OR'd together. messageID The message ID, defined in the message's code field in the sams file. . . . Any format arguments for the message string. DESCRIPTION The dce_svc_printf() routine is the normal call for writing or displaying serviceability messages. It cannot be called with a literal text argument. Instead, the message text is retrieved from a message catalog or an in-core message table. These are generated by the sams utility, which in turn outputs sets of tables from which the messages are extracted for output. There are two main ways in which to call the routine. If a message has been defined in the sams file with both sub-component and attributes specified, then the sams output will include a "convenience macro" for the message that can be passed as the single argument to dce_svc_printf(), for example: dce_svc_printf(SIGN_ON_MSG); The convenience macro's name will be generated from the uppercase version of the message's code value (as specified in the sams file), with the string _MSG appended. If a convenience macro is not generated, or if you want to override some of the message's attributes at the time of output, then you must call the routine in its long form. An example of this form of the call looks as follows: dce_svc_printf(DCE_SVC(app_svc_handle, ""), app_subcomponent, svc_c_sev_error | svc_c_route_stderr, messageID); DCE_SVC() is a macro that must be passed as the first argument to dce_svc_printf() if a convenience macro is not being used. It takes two arguments: + The caller's serviceability handle + A format string for the message that is to be output The format string is for use with messages that have been coded with argument specifiers. It is a character string consisting of the argument types as they would be passed to a printf call. If the message is to be routed to a binary file, the format is extended to include a %b specifier; using %b in a different routing will give unpredictable results. The %b specifier takes two arguments: an integer size, and a buffer pointer. The remaining arguments passed to dce_svc_printf() are as follows: + subcomponent table index This symbol is declared in the sub-component list coded in Part II of the sams file; its value is used to index into the subtable of messages in which the desired message is located. + message attribute(s) This argument consists of one or more attributes to be applied to the message that is to be printed. Note that you must specify at least one severity here. Multiple attributes are OR'd together, as shown in the following example. There are four categories of message attributes: Routing The available routing attribute constants are: - svc_c_route_stderr - svc_c_route_nolog However, most routing is done either by passing specially-formatted strings to dce_svc_routing() or by environment variable values. Note that using svc_c_route_nolog without using svc_c_route_stderr will result in no message being generated. Severity The available severity attribute constants are: - svc_c_sev_fatal - svc_c_sev_error - svc_c_sev_warning - svc_c_sev_notice - svc_c_sev_notice_verbose Action The available message action attribute constants are: - svc_c_action_abort - svc_c_action_exit_bad - svc_c_action_exit_ok - svc_c_action_brief - svc_c_action_none Note that svc_c_action_brief is used to suppress the standard prolog. Debug Level Nine different debug levels can be specified (svc_c_debug1...svc_c_debug9 or svc_c_debug_off). + message ID This argument consists of the message's code, as declared in the sams file. ERROR CODES This routine has no return value. RELATED INFORMATION Functions: dce_svc_register DCE_SVC_DEFINE_HANDLE 4 dce_svc_register NAME dce_svc_register - Registers a serviceability message table SYNOPSIS #include dce_svc_handle_t dce_svc_register( dce_svc_subcomp_t *table, const idl_char *component_name, error_status_t *status ); PARAMETERS Input table A message table structure (defined in a header file generated by sams during compilation). component_name The serviceability name of the component, defined in the component field of the sams file. Output status Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. DESCRIPTION The dce_svc_register() routine registers a serviceability message table. An application must call either it (or the DCE_SVC_DEFINE_HANDLE() macro) in order to set up its table(s) and obtain the serviceability handle it must have in order to use the serviceability interface. Two parameters are required for the call: table is a pointer to the application's serviceability table, defined in a file called dceappsvc.h generated by the sams utility. component_name is a string whose value is app, which is defined in the component field of the sams file in which the serviceability messages are defined. On error, this routine returns NULL and fills in status with an error code. ERROR CODES The following serviceability status codes are defined: svc_s_assertion_failed A programmer-developed compile-time assertion failed. svc_s_at_end No more data is available. svc_s_bad_routespec See svcroute for information on routing specification format. svc_s_cantopen Permission denied or file does not exist; consult errno. svc_s_no_filter Attempted to send data to the filter-control handle for a component that does not have a filter registered. svc_s_no_memory Could not allocate memory for message table, string copy or other internal requirement. svc_s_no_stats The definition of the return value has not been specified. svc_s_ok Operation performed. svc_s_unknown_component Could not find the service handle for a component. RELATED INFORMATION Functions: dce_svc_debug_routing dce_svc_debug_set_levels dce_svc_define_filter dce_svc_routing dce_svc_unregister 4 dce_svc_routing NAME dce_svc_routing - Specifies routing of serviceability messages SYNOPSIS #include #include void dce_svc_routing( unsigned char *where, error_status_t *status ); PARAMETERS Input where A three-field routing string, as described in svcroute. Output status Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. DESCRIPTION The dce_svc_routing() routine specifies how normal (non-debug) serviceability messages are routed. The where parameter is a three- field routing string, as described in svcroute. For convenience, the first field of the routing specifier (which indicates the message severity type to which the routing is to be applied) may be an * (asterisk) to indicate that all messages, whatever their severity, should be routed as specified. If the routine is called before the component is registered (with the dce_svc_register() routine), the routing is stored until it is needed. In case of error, the status parameter is filled in with an error code. ERROR CODES See dce_svc_register. FILES dce/service.idl 4 dce_svc_set_progname NAME dce_svc_set_progname - Sets an application's program name SYNOPSIS #include void dce_svc_set_progname( char *program_name, error_status_t *status ); PARAMETERS Input program_name A string containing the name that is to be included in the text of all serviceability messages that the application generates during the session. Output status Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. DESCRIPTION This function sets the application's program name, which is included in serviceability messages. This allows serviceability messages from more than one application to be written to the same file and still be distinguishable as to their separate origins. If dce_svc_set_progname() is not called, the application's generated serviceability messages will be identified by its process ID. EXAMPLES Suppose an application sets its program name to be "demo_program", as shown: dce_svc_set_progname("demo_program", &status); Serviceability messages generated by the program will as a result look like the following: 1994-04-05-20:13:34.500+00:00I----- demo_program NOTICE app main.c 123 0xa444e208 message text If the application does not set its program name, its generated serviceability messages will have the following form: 1994-04-05-20:13:34.500+00:00I----- PID#9467 NOTICE app main.c 123 0xa444e208 message text ERROR CODES See dce_svc_register. RELATED INFORMATION Functions: dce_printf dce_svc_printf DCE_SVC_DEBUG 4 dce_svc_table NAME dce_svc_table - Returns a registered component's subcomponent table SYNOPSIS #include #include void dce_svc_table( dce_svc_string_t component, dce_svc_subcomparray_t *table, error_status_t *status ); PARAMETERS Input component The name of the serviceability-registered component, defined in the component field of the application's sams file. Output table An array of elements, each of which describes one of the component's serviceability sub-components (as defined in its sams file). status Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. DESCRIPTION The dce_svc_table routine returns the serviceability subcomponent table registered with the specified component. The returned table consists of an array of elements, each of which describes one sub- component. Each element consists of four fields, which contain the sub-component name, its description, its message catalog ID, and the current value of its debug message level. The first three of these values are specified in the sams file which is processed during the application's compilation, and from which the application's message catalogs and other serviceability and message files are generated. EXAMPLES The following code fragment shows how the remote operation might be called from an application's client side, and how the results might be printed out: #include #include handle_t svc_bind_handle; dce_svc_string_t component; dce_svc_subcomparray_t subcomponents_table; error_status_t remote_status; int i; dce_svc_inq_table( svc_bind_handle, component, &subcomponents_table, &remote_status ); fprintf(stdout, "Subcomponent table size received is: %d...\n", subcomponents_table.tab_size); fprintf(stdout, "Subcomponent table contents are:\n"); for (i = 0; i < subcomponents_table.tab_size; i++) { fprintf(stdout, "Name: %s\n", subcomponents_table.table[i].sc_name); fprintf(stdout, "Desc: %s\n", subcomponents_table.table[i].sc_descr); fprintf(stdout, "Msg Cat ID: 0x%8.8lx\n", (long) subcomponents_table.table[i].sc_descr_msgid); fprintf(stdout, "Active debug level: %d\n\n", subcomponents_table.table[i].sc_level); } ERROR CODES See dce_svc_register. FILES dce/service.idl 4 dce_svc_unregister NAME dce_svc_unregister - Destroys a serviceability handle SYNOPSIS #include void dce_svc_unregister( dce_svc_handle_t handle, error_status_t *status ); PARAMETERS Input handle The application's serviceability handle, originally returned by a call to dce_svc_register(), or filled in by the DCE_SVC_DEFINE_HANDLE() macro Output status Returns the status code from this operation. The status code is a value that indicates whether the routine completed successfully and if not, why not. DESCRIPTION The dce_svc_unregister() routine destroys a serviceability handle. Calling it closes any open serviceability message routes and frees all allocated resources associated with the handle. The handle parameter is the serviceability handle that was originally returned by the call to dce_svc_register(), or filled in by the DCE_SVC_DEFINE_HANDLE() macro. On error, the routine fills in status with an error code. Note that it is not usually necessary to call this routine, since the normal process exit will perform the required cleanup. ERROR CODES See dce_svc_register. RELATED INFORMATION Functions: dce_svc_register 3 dce_svc_macros NAME DCE_SVC_INTRO - Introduction to the DCE serviceability macros DESCRIPTION The DCE_SVC_DEFINE_HANDLE macro is used to create a serviceability handle. This can be useful in a library that has no explicit initialization routine in which a call to dce_svc_register() could be added. The remaining macros can be "compiled out" of production code, or left in to aid diagnostics, depending on whether or not DCE_DEBUG (normally found in dce/dce.h) is defined. The DCE Serviceability Macros The serviceability macros are as follows, listed in alphabetical order: DCE_SVC_DEBUG() Used to generate debugging output. DCE_SVC_DEBUG_ATLEAST() Can be used to test the debug level of a subcomponent for a specified handle. Tests whether the debug level is at least at the specified level. DCE_SVC_DEBUG_IS() Can be used to test the debug level of a subcomponent for a specified handle. Tests for an exact match with the specified level. DCE_SVC_DEFINE_HANDLE() Registers a serviceability message table. DCE_SVC_LOG() Generates debugging output based on a message defined in an application's sams file. FILES dce/service.idl dce/dce_svc.h RELATED INFORMATION BOOKS: OSF DCE Application Development Guide 4 DCE_SVC_DEBUG NAME DCE_SVC_DEBUG - Macro to output a serviceability debug message SYNOPSIS #include DCE_SVC_DEBUG( ( dce_svc_handle_t handle, const unsigned32 table_index, unsigned32 debug_level, char * format, ..) ); PARAMETERS Input handle The caller's serviceability handle. table_index The message's sub-component name (defined in the sams file). debug_level Serviceability debug level for the message. format The message string. . . . Format arguments, if any. DESCRIPTION The DCE_SVC_DEBUG macro is used to generate debugging output. Because it is a macro that takes a variable number of arguments, the entire parameter list must be enclosed in two sets of parentheses. The handle and table_index parameters are as described for dce_svc_printf(). In contrast to the normal operation of the serviceability interface, DCE_SVC_DEBUG requires the caller to specify the message as a string literal in the call, rather than by defining it in the application's sams file specifying the message by a message ID. The debug_level argument indicates the level of detail associated with this message and must be in the range svc_c_debug1 to svc_c_debug9. Thus the value of debug_level associates the message with one of nine "levels", and whether or not the message is actually generated at run time will depend on what debugging level has been set for the application. The level can be set by the application itself (by a call to dce_svc_debug_set_levels() or dce_svc_debug_routing()) or by the value of an environment variable or a serviceability routing file; see svcroute for further information. The significance of the various levels is application-defined, but in general the higher levels (numbers) imply more detail in debugging output. The format and . . . parameters are passed directly to fprintf() or its equivalent. RELATED INFORMATION Functions: dce_svc_debug_routing dce_svc_debug_set_levels dce_svc_printf dce_svc_routing Files: svcroute 4 DCE_SVC_DEBUG_ATLEAST NAME DCE_SVC_DEBUG_ATLEAST - Macro to test a component's serviceability debug level SYNOPSIS #include DCE_SVC_DEBUG_ATLEAST( dce_svc_handle_t handle, const unsigned32 table_index, unsigned32 debug_level ); PARAMETERS Input handle The caller's serviceability handle. table_index The sub-component name (defined in the sams file) whose debug level is being tested. debug_level Debug level being tested. DESCRIPTION If serviceability debug code was enabled (by defining DCE_DEBUG) during compilation, the DCE_SVC_DEBUG_ATLEAST and DCE_SVC_DEBUG_IS macros can be used to test the debug level of a subcomponent (specified by table_index) for the specified handle. DCE_SVC_DEBUG_ATLEAST tests whether the debug level is at least at the specified level. DCE_SVC_DEBUG_IS tests for an exact match with the specified level. In either case, the specified level should be a number between 1 and 9. RELATED INFORMATION Functions: DCE_SVC_DEBUG DCE_SVC_DEBUG_IS DCE_SVC_LOG 4 DCE_SVC_DEBUG_IS NAME DCE_SVC_DEBUG_IS - Macro to test a component's serviceability debug level SYNOPSIS #include DCE_SVC_DEBUG_IS( dce_svc_handle_t handle, const unsigned32 table_index, unsigned32 debug_level ); PARAMETERS Input handle The caller's serviceability handle. table_index The name of the sub-component name (defined in the sams file) whose debug level is to be tested. debug_level The serviceability debug level being tested. DESCRIPTION If serviceability debug code was enabled (by defining DCE_DEBUG) during compilation, the DCE_SVC_DEBUG_ATLEAST and DCE_SVC_DEBUG_IS macros can be used to test the debug level of a subcomponent (specified by table_index) for the specified handle. DCE_SVC_DEBUG_ATLEAST tests whether the debug level is at least at the specified level. DCE_SVC_DEBUG_IS tests for an exact match with the specified level. In either case, the specified level should be a number between 1 and 9. RELATED INFORMATION Functions: DCE_SVC_DEBUG DCE_SVC_DEBUG_ATLEAST DCE_SVC_LOG 4 DCE_SVC_DEFINE_HANDLE NAME DCE_SVC_DEFINE_HANDLE - Macro to create a serviceability handle SYNOPSIS #include DCE_SVC_DEFINE_HANDLE( dce_svc_handle_t handle, dce_svc_subcomp_t *table, const idl_char *component_name ); PARAMETERS Input table A message table structure (defined in a header file generated by sams during compilation). component_name The serviceability name of the component, defined in the component field of the sams file. Output handle A serviceability handle structure which will be filled in by the macro. DESCRIPTION There are two ways to register a serviceability table preparatory to using the serviceability interface in an application. The first is to create a global variable using the DCE_SVC_DEFINE_HANDLE macro. The first parameter is the serviceability handle, the second is a pointer to the component's message table, and the third is the name of the serviceability component (application). The macro creates a skeleton variable that will be completed the first time the handle is used. This can be useful when writing library code that has no explicit initialization routine. The second method is to call the dce_svc_register() routine. RELATED INFORMATION Functions: dce_svc_register 4 DCE_SVC_LOG NAME DCE_SVC_LOG - Macro to output a binary form of a serviceability debug message SYNOPSIS #include DCE_SVC_LOG( ( dce_svc_handle_t handle, const unsigned32 table_index, unsigned32 debug_level, const unsigned32 messageid, char * format, . . .) ); PARAMETERS Input handle The caller's serviceability handle. table_index The message's sub-component name (defined in the sams file). debug_level Serviceability debug level for the message. messageid A message ID, defined in the message's code field in the sams file. format A message format specifier string (used if messageid cannot be found). . . . Any format arguments for the message string. DESCRIPTION The DCE_SVC_LOG macro is used to generate debugging output based on a message defined in an application's sams file (in this respect it is unlike DCE_SVC_DEBUG, in which the message is specified as a literal string parameter). Because it is a macro that takes a variable number of arguments, the entire parameter list must be enclosed in two sets of parentheses. The handle and table_index parameters are as described for dce_svc_printf(). The message can be specified in either one of two ways: by messageid, identifying a message defined in the normal way in the application's sams file; or as a string literal paramater (format). The format string is used only if the specified messageid cannot be found. DCE_SVC_LOG generates a record in the serviceability binary format, not a conventional serviceability message as such. The complete message text is not normally written; instead, only the message ID (the messageid specified in the macro parameter), and its format arguments (if any) are written. When the binary log is read (see svcdumplog), the text of the message is reconstructed from the application's installed message catalog. However, if the original message was generated from the format argument, then the entire message text is written to the binary record. The debug_level argument indicates the level of detail associated with the message and must be in the range svc_c_debug1 to svc_c_debug9. Thus the value of debug_level associates the message with one of nine "levels", and whether or not the message is actually generated at run time will depend on what debugging level has been set for the application. The level can be set by the application itself (by a call to dce_svc_debug_set_levels() or dce_svc_debug_routing()) or by the value of an environment variable or a serviceability routing file; see svcroute for further information. The significance of the various levels is application-defined, but in general the higher levels (numbers) imply more detail in debugging output. RELATED INFORMATION Functions: DCE_SVC_DEBUG DCE_SVC_DEBUG_ATLEAST DCE_SVC_DEBUG_IS 3 dced_intro NAME dced_intro - Introduction to the DCE Host daemon routines DESCRIPTION This introduces the DCE Host Daemon application programming interface: the dced API. This API gives management applications remote access to various data, servers, and services on DCE hosts. Servers manage their own configuration in the local dced by using the routines starting with dce_server, introduced in the dce_server_intro reference page. THE DCED API NAMING CONVENTIONS All of the dced API routine names begin with the dced_ prefix. This API contains some specialized routines that operate on services represented by the following keywords in the routine names: hostdata The host data management service stores host-specific data such as the host name, the host's cell name, and other data, and it provides access to these data items. server The server control service configures, starts, and stops servers, among other things. Applications must distinguish two general states of server control: server configuration (srvrconf) and server execution (srvrexec). secval The security validation service maintains a host's principal identity and ensures applications that the DCE Security daemon is genuine. keytab The key table management service remotely manages key tables. The dced also provides the endpoint mapper service which has its own API, described with the RPC API. These routines begin with rpc_ep and rpc_mgmt_ep. Since some of the dced daemon's services require the same operations (but on different data types), the dced API also contains generic routines that may operate on more than one of the above services. For example, you use the routine dced_object_read() to read a data item (object) from the hostdata, srvrconf, srvrexec, or keytab services. FILES dce/dced_base.h dce/dced.h dce/dced_data.h dce/rpctypes.idl dce/passwd.idl dce/sec_attr_base.idl RELATED INFORMATION ROUTINES: dced_* API. BOOKS: OSF DCE Application Development Guide 4 Dced_Binding_Routines A binding must be established to a dced service on a particular host before you can use any other dced routines. The resources of the dced binding should also be released when an application is finished with the service. dced_binding_create Establishes a dced binding to a host service dced_binding_from_rpc_binding Establishes a dced binding to a dced service on the host specified in an already-established RPC binding handle to any server dced_binding_set_auth_info Sets authentication, authorization, and protection level information for a dced binding handle dced_binding_free Releases the resources of a dced binding handle 5 dced_binding_create NAME dced_binding_create - Establishes a dced binding to one of the host services of a remote (or the local) dced. SYNOPSIS #include void dced_binding_create( dced_string_t service, unsigned32 binding_flags, dced_binding_handle_t *dced_bh, error_status_t *status ); PARAMETERS Input service A character string that specifies a host daemon service name and an optional remote host. A service name is specified with one of the following: hostdata, srvrconf, srvrexec, secval, or keytab. The format of a complete service and host specification is one of the following: service_name A service at the local host. Pre-existing defined values include: dced_c_service_hostdata dced_c_service_srvrconf dced_c_service_srvrexec dced_c_service_secval dced_c_service_keytab service_name@hosts/host_name A service at a host anywhere in the local namespace. /.:/hosts/host_name/config/service_name A complete specification for service_name@host, where the host is anywhere in the local namespace. /.../cell/hosts/host_name/config/service_name A service at a host anywhere in the global namespace. binding_flags Currently, the only valid flag value is dced_c_binding_syntax_default. Output dced_bh Returns a dced binding handle which is a pointer to an opaque data structure containing information about an RPC binding, the host, the host service, and a local cache. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok dce_cf_e_no_mem dced_s_invalid_arg dced_s_no_memory dced_s_unknown_service rpc_s_entry_not_found rpc_s_incomplete_name rpc_s_invalid_object rpc_s_name_service_unavailable rpc_s_no_memory rpc_s_no_more_bindings rpc_s_no_ns_permission DESCRIPTION The dced on each DCE host maintains the host services and provides a remote interface to them. The host services include the following: + Endpoint Mapper + Host Data Management (hostdata) + Server Management: Including Server Configuration (srvrconf) and Server Execution (srvrexec) + Security Validation (secval) + Key Table Management (keytab) The dced_binding_create() routine establishes a dced binding to a dced service and it (or dced_binding_from_rpc_binding()) must be the first dced API routine called before an application can access one of the host services with other dced API routines. When an application is finished with the service, it should call the dced_binding_free() routine to free resources. To establish a dced binding to your local host's dced, you can use the service name by itself, and do not need to specify a host. To access the endpoint map directly, use rpc_mgmt_ep_elt_inq_begin() and associated routines. EXAMPLES This example establishes a dced binding to the server configuration service on the host patrick. dced_binding_handle_t dced_bh; error_status_t status; dced_binding_create("srvrconf@hosts/patrick", dced_c_binding_syntax_default, &dced_bh, &status); . . /* Other routines including dced API routines. */ . dced_binding_free(dced_bh, &status); RELATED INFORMATION Routines: dced_binding_free dced_binding_from_rpc_binding Books: OSF DCE Application Development Guide. 5 dced_binding_from_rpc_binding NAME dced_binding_from_rpc_binding - Establishes a dced binding to one of the host services on the host specified in an existing RPC binding handle. SYNOPSIS #include void dced_binding_from_rpc_binding( dced_service_type_t service, handle_t rpc_bh, dced_binding_handle_t *dced_bh, error_status_t *status ); PARAMETERS Input service A variable that specifies one of the host services. A valid variable name includes one of the following: dced_e_service_type_hostdata dced_e_service_type_srvrconf dced_e_service_type_srvrexec dced_e_service_type_secval dced_e_service_type_keytab rpc_bh An RPC binding handle to some server. Output dced_bh Returns a dced binding handle which is a pointer to an opaque data structure containing information about an RPC binding, the host, the host service, and a local cache. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok dced_s_no_memory dced_s_unknown_service ept_s_cant_perform_op ept_s_database_invalid ept_s_invalid_context ept_s_invalid_entry rpc_s_comm_failure rpc_s_fault_context_mismatch rpc_s_invalid_arg rpc_s_invalid_binding rpc_s_no_more_elements rpc_s_wrong_kind_of_binding DESCRIPTION The dced on each DCE host maintains the host services and provides a remote interface to the services. The dced_binding_from_rpc_binding() routine establishes a dced binding to a dced service, and it (or dced_binding_create()) must be the first dced API routine called before an application can access one of the host services with other dced routines. When an application is finished with the service, it should call the dced_binding_free() routine to free resources. Prior to using the RPC binding in this routine, make a copy of the binding by using the rpc_binding_copy() routine. This is necessary if the application needs to continue using the RPC binding because otherwise the dced binding takes over the RPC binding. The RPC binding may be obtained from a call to specific RPC runtime routines such as rpc_binding_from_string_binding, rpc_ns_binding_import_next, or rpc_ns_binding_lookup_next. EXAMPLES This example obtains an RPC binding from a string binding, and it later makes a copy of the RPC binding for use in the dced_binding_from_rpc_binding() call. handle_t rpc_bh, binding_handle; dced_binding_handle_t dced_bh; dced_service_type_t service_type; error_status_t status; unsigned_char_t string_binding[STRINGLEN]; . . . rpc_binding_from_string_binding( string_binding, &binding_handle, &status ); . . . rpc_binding_copy( binding_handle, &rpc_bh, &status ); dced_binding_from_rpc_binding( service_type, rpc_bh, &dced_bh, &status ); . . /* Other routines including dced API routines. */ . dced_binding_free(dced_bh, &status); RELATED INFORMATION Routines: dced_binding_free dced_binding_create rpc_ns_binding_import_next rpc_ns_binding_lookup_next rpc_binding_from_string_binding rpc_binding_copy Books: OSF DCE Application Development Guide. 5 dced_binding_set_auth_info NAME dced_binding_set_auth_info - Sets authentication and authorization information for a dced binding handle SYNOPSIS #include void dced_binding_set_auth_info( dced_binding_handle_t dced_bh, unsigned32 protect_level, unsigned32 authn_service, rpc_auth_identity_handle_t authn_identity, unsigned32 authz_service, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for which to set the authentication and authorization information. protect_level Specifies the protection level for dced API calls that will use the dced binding handle dced_bh. authn_service Specifies the authentication service to use for dced API calls that will use the dced binding handle dced_bh. authn_identity Specifies a handle for the data structure that contains the calling application's authentication and authorization credentials appropriate for the selected authn_service and authz_service services. Specify NULL to use the default security login context for the current address space. authz_service Specifies the authorization service to be implemented by dced for the host service accessed. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok dced_s_bad_binding dced_s_no_support ept_s_not_registered rpc_s_authn_authz_mismatch rpc_s_binding_incomplete rpc_s_comm_failure rpc_s_invalid_binding rpc_s_mgmt_op_disallowed rpc_s_rpcd_comm_failure rpc_s_unknown_authn_service rpc_s_unsupported_protect_level rpc_s_wrong_kind_of_binding DESCRIPTION The dced_binding_set_auth_info() routine sets up the dced binding handle so it can be used for authenticated calls that include authorization information. The rpc_binding_set_auth_info routine performs in the same way as this one. See it for details of the parameters and values. Prior to calling this routine, the application must have established a valid dced binding handle by calling either the dced_binding_create() or dced_binding_from_rpc_binding() routine. EXAMPLES This example establishes a dced binding to a host's key table service, and then it calls dced_binding_set_auth_info() so that the application is authorized to access remote key tables by using additional calls to the key table service. dced_binding_handle_t dced_bh; error_status_t status; dced_binding_create( (dced_string_t)"keytab@hosts/patrick", dced_c_binding_syntax_default, &dced_bh, &status ); dced_binding_set_auth_info( dced_bh, rpc_c_protect_level_default, rpc_c_authn_pkt_privacy, NULL, rpc_c_authz_dce, &status ); . . /* Other routines including dced API routines. */ . RELATED INFORMATION Routines rpc_binding_set_auth_info dced_binding_create dced_binding_from_rpc_binding Books: OSF DCE Application Development Guide. 5 dced_binding_free NAME dced_binding_free - Releases the resources associated with a dced binding handle SYNOPSIS #include void dced_binding_free( dced_binding_handle_t dced_bh, error_status_t *status ); PARAMETERS Input dced_bh Specifies a dced binding handle to free for a dced service on a specific host. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok rpc_s_invalid_binding rpc_s_wrong_kind_of_binding DESCRIPTION The dced_binding_free() routine frees resources used by a dced binding handle and referenced information. Use this routine when your application is finished with a host service to break the communication between your application and the dced. The dced binding handle and referenced information is created with the dced_binding_create() or dced_binding_from_rpc_binding() routine. RELATED INFORMATION Routines: dced_binding_create dced_binding_from_rpc_binding Books: OSF DCE Application Development Guide. 4 Generic_Entry_Routines All data maintained by dced is managed as entries. Most of the services of dced have lists of entries traversed with a cursor that describe where the actual data is maintained. dced_entry_add Adds a keytab or hostdata entry dced_entry_remove Removes a hostdata or keytab data entry from dced dced_initialize_cursor Obtains a list of data entries from dced and sets a cursor at the beginning of the list dced_entry_get_next Obtains the next data entry from a list of entries dced_release_cursor Releases the resources associated with a cursor which traverses a service's list of entries dced_list_get Returns the list of data entries maintained by a DCE Host service dced_list_release Releases the resources of a list of entries dced_inq_id Obtains the UUID associated with an entry name dced_inq_name Obtains the name associated with an entry UUID 5 dced_entry_add NAME dced_entry_add - Adds a keytab or hostdata entry to a host's dced for an existing file on that host SYNOPSIS #include void dced_entry_add( dced_binding_handle_t dced_bh, dced_entry_t *entry, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for a dced service on a specific host. Input/Output entry Specifies the data entry to add to the service. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok db_s_readonly db_s_store_failed dced_s_already_exists dced_s_bad_binding dced_s_import_cant_access dced_s_no_support rpc_s_binding_has_no_auth sec_acl_invalid_permission uuid_s_no_address DESCRIPTION The dced_entry_add() routine adds a data entry to a dced service. The data it refers to must already exist in a file on the dced's host. You can only add hostdata or keytab entries. A service's data entries do not contain the actual data. Instead, they contain a UUID, a name for the entry, a brief description of the item, and a storage tag that describes the location of the actual data. In the cases of the hostdata and keytab services, the data for each entry is stored in a file. The dced uses this two-level scheme so that it can manipulate different kinds of data in the same way and so names are independent of local file system requirements. The hostdata and keytab services each have their respective routines to create new data and at the same time, add a new entry to the appropriate service. These routines are dced_hostdata_create() and dced_keytab_create(). Prior to calling the dced_entry_add() routine, the application must have established a valid dced binding handle for the hostdata or keytab service by calling either the dced_binding_create() or dced_binding_from_rpc_binding() routine. EXAMPLES The following example shows how to add a printer configuration file to the hostdata service. The example creates a dced binding to the local hostdata service, an entry data structure is filled in with the storage tag containing the full path of the existing configuration file, and finally the dced_entry_add() routine is called. dced_binding_handle_t dced_bh; error_status_t status; dced_entry_t entry; dced_binding_create( dced_c_service_hostdata, dced_c_binding_syntax_default, &dced_bh, &status ); uuid_create( &(entry.id), &status ); entry.name = (dced_string_t)("NEWERprinter"); entry.description = (dced_string_t) ("Configuration for a new printer."); entry.storage_tag = (dced_string_t)("/etc/NEWprinter"); dced_entry_add( dced_bh, &entry, &status ); . . . RELATED INFORMATION Routines: dced_entry_remove dced_hostdata_create dced_keytab_create dced_binding_create dced_binding_from_rpc_binding Books: OSF DCE Application Development Guide. 5 dced_entry_remove NAME dced_entry_remove - Removes a hostdata or keytab data entry from a dced service's list of entries SYNOPSIS #include void dced_entry_remove( dced_binding_handle_t dced_bh, uuid_t *entry_uuid, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for a dced service on a specific host. entry_uuid Specifies the UUID of the entry to be removed from the service. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok db_s_del_failed db_s_key_not_found db_s_readonly dced_s_bad_binding dced_s_no_support dced_s_not_found sec_acl_invalid_permission DESCRIPTION The dced_entry_remove() routine removes an entry from the hostdata or keytab service entry list of dced. It does not remove the actual data stored in the file, but makes it inaccessible from a remote host by way of the dced's user interfaces which include the dced API and the DCE control program, dcecp. Each host service that maintains data also maintains a list of data entries. A data entry contains a name, a UUID, a brief description, and a storage tag indicating the location of the actual data. To delete both the data and entry for the hostdata, keytab, or srvrconf services use dced_hostdata_delete(), dced_keytab_delete(), or dced_server_delete(), respectively. (The srvrexec service is maintained only be dced and the secval service does not maintain data, so you cannot remove data for these services.) Applications commonly obtain an entry by traversing the entry list using the dced_entry_get_next() routine with its associated cursor routines. Prior to calling the dced_entry_remove() routine, the application must have established a valid dced binding handle to the hostdata or keytab service by calling either the dced_binding_create() or dced_binding_from_rpc_binding() routine. RELATED INFORMATION Routines: dced_hostdata_delete dced_keytab_delete dced_server_delete dced_initialize_cursor dced_binding_create dced_binding_from_rpc_binding Books: OSF DCE Application Development Guide. 5 dced_initialize_cursor NAME dced_initialize_cursor - Sets a cursor to the start of a cached list of data entries for a dced service SYNOPSIS #include void dced_initialize_cursor( dced_binding_handle_t dced_bh, dced_cursor_t *cursor, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for a dced service on a specific host. Output cursor Returns the cursor used to traverse the list of data entries, one at a time. The cursor is an opaque data structure that is used to keep track of the entries between invocations of the dced_entry_get_next() routine. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok db_s_bad_index_type db_s_iter_not_allowed db_s_key_not_found dced_s_bad_binding dced_s_no_memory dced_s_no_support sec_acl_invalid_permission DESCRIPTION The dced_initialize_cursor() routine sets a cursor at the start of a DCE host service's list of data entries. The cursor is then used in subsequent calls to dced_entry_get_next() to obtain individual data entries. When the application is finished traversing the entry list, it should call dced_release_cursor() to free the resources allocated for the cursor. The valid services for this routine that have entry lists include hostdata, srvrconf, srvrexec, and keytab. If a service's entry list is small, it may be more efficient to obtain the entire list using the dced_list_get() routine rather than using cursor routines. This is because dced_list_get() guarantees the list is obtained with one remote procedure call. However, your application is scalable if you use the cursor routines because if an entry list is very large, it may be more efficient (or even necessary) to obtain the list in chunks with more than one remote procedure call. Prior to calling the dced_initialize_cursor() routine, the application must have established a valid dced binding handle by calling either the dced_binding_create() or dced_binding_from_rpc_binding() routine. RELATED INFORMATION Routines: dced_entry_get_next dced_release_cursor dced_list_get dced_binding_create dced_binding_from_rpc_binding Books: OSF DCE Application Development Guide. 5 dced_entry_get_next NAME dced_entry_get_next - Obtains one data entry from a list of entries of a dced service SYNOPSIS #include void dced_entry_get_next( dced_cursor_t cursor, dced_entry_t **entry, error_status_t *status ); PARAMETERS Input/Output cursor Specifies the entry list's cursor that points to an entry, and returns the cursor advanced to the next entry in the list. Output entry Returns a pointer to an entry. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok dced_s_no_more_entries DESCRIPTION The dced_entry_get_next() routine obtains a pointer to a data entry, and advances the cursor to the next entry in the list. This routine is commonly used in a loop to traverse a host service's entry list. The data is obtained in an undetermined order. Prior to using this routine, the application must call dced_initialize_cursor() to obtain a list of entries and to establish the beginning of the cursor. When the application is finished traversing the entry list, it should call dced_release_cursor() to release resources. A data entry does not contain the actual data, but it contains the name, identity, description, and storage location of the data. In the cases of hostdata and keytab services, the data for each entry is stored in a file. In the cases of srvrconf and srvrexec services, data is stored in memory. The dced uses this two-level scheme so that it can manipulate different kinds of data in the same way. Prior to using the dced_entry_get_next() routine, the application must have established a valid dced binding handle by calling either the dced_binding_create() or dced_binding_from_rpc_binding() routine. EXAMPLES In the following example, a dced binding is obtained from a service type and an existing rpc binding handle. After establishing an entry list cursor, the dced_entry_get_next() routine obtains an entry, one at a time, and the name and description of each entry is displayed until the entry list is exhausted. dced_binding_from_rpc_binding( service_type, rpc_bh, &dced_bh, &status ); dced_initialize_cursor( dced_bh, &cursor, &status ); for( ; ; ) { /* forever loop */ dced_entry_get_next( cursor, &entry, &status ); if (status != error_status_ok) break; display(entry->name, entry->description); /* app. specific */ } dced_release_cursor( &cursor, &status ); dced_binding_free( dced_bh, &status ); RELATED INFORMATION Routines: dced_initialize_cursor dced_release_cursor dced_binding_create dced_binding_from_rpc_binding Books: OSF DCE Application Development Guide. 5 dced_release_cursor NAME dced_release_cursor - Releases the resources of a cursor which traverses a dced service's list of entries SYNOPSIS #include void dced_release_cursor( dced_cursor_t *cursor, error_status_t *status ); PARAMETERS Input/Output cursor Specifies the cursor for which resources are released. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The only possible status code is: error_status_ok DESCRIPTION The dced_release_cursor() routine releases the resources of a cursor initially set by the dced_initilalize_cursor() routine and used by the dced_entry_get_next() routine. Prior to calling this routine, the application must have first established a valid dced binding handle by calling either the dced_binding_create() or dced_binding_from_rpc_binding() routine, and then the application must have called the dced_initialize_cursor() routine. RELATED INFORMATION Routines: dced_initialize_cursor dced_entry_get_next dced_binding_create dced_binding_from_rpc_binding Books: OSF DCE Application Development Guide. 5 dced_list_get NAME dced_list_get - Returns the list of data entries maintained by a dced service on a specific host SYNOPSIS #include void dced_list_get( dced_binding_handle_t dced_bh, dced_entry_list_t *list, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for a dced service on a specific host. Output list Returns a list of data entries for the service. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok dced_s_bad_binding dced_s_no_memory dced_s_no_support sec_acl_invalid_permission DESCRIPTION The dced_list_get() routine obtains all the data entries for a dced service on a specific host. The list of data entries obtained is not the actual data. Each entry contains a UUID, name, description, and storage tag that describes where the data is located (for example, a file name or memory location). Call the dced_list_release() routine when your application is finished with the entry list to release resources allocated with dced_list_get() routine. If a service's entry list is small, it may be efficient to obtain the entire list using the dced_list_get() routine because it guarantees the list is obtained with one remote procedure call. However, to make your application scalable, use the dced_initialize_cursor(), dced_entry_get_next(), and dced_release_cursor() set of routines because if an entry list is very large, it may be more efficient (or even necessary) to obtain the list in chunks with more than one remote procedure call. Prior to calling this routine, the application must have established a valid dced binding handle by calling either the dced_binding_create() or dced_binding_from_rpc_binding() routine. EXAMPLES In the following example, a dced binding is obtained from a service type and an existing rpc binding handle. The list of entries for the service is obtained with the dced_list_get() routine and each entry's name and description are displayed. dced_binding_from_rpc_binding( service_type, rpc_bh, &dced_bh, &status ); dced_list_get( dced_bh, &entries, &status ); for(i=0; i void dced_list_release( dced_binding_handle_t dced_bh, dced_entry_list_t *list, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for a dced service on a specific host. InputOutput list Specifies a list of data entries for the service. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The only possible status code is: error_status_ok DESCRIPTION The dced_list_release() routine releases the resources allocated for a list of data entries previously retrieved by the dced_list_get() routine. Prior to calling this routine, the application must have first established a valid dced binding handle by calling either the dced_binding_create() or dced_binding_from_rpc_binding() routine, and then the application must have called the dced_list_get() routine. RELATED INFORMATION Routines: dced_list_get dced_binding_create dced_binding_from_rpc_binding Books: OSF DCE Application Development Guide. 5 dced_inq_id NAME dced_inq_id - Obtains the entry UUID that dced associates with a name SYNOPSIS #include void dced_inq_id( dced_binding_handle_t dced_bh, dced_string_t name, uuid_t *uuid, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for a dced service on a specific host. name Specifies the name for which to obtain the uuid. Output uuid returns the UUID associated with the name input. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok db_s_bad_index_type db_s_iter_not_allowed db_s_key_not_found dced_s_not_found sec_acl_invalid_permission DESCRIPTION The dced_inq_id() routine obtains the UUID associated with a name in a service of a specific host's dced. Applications and administrators use strings maintained by dced to identify data, but dced and its API must associate each data entry with a UUID. This routine is valid for the host-data, srvrconf, srvrexec, and keytab services. Prior to calling this routine, the application must have established a valid dced binding handle by calling either the dced_binding_create() or dced_binding_from_rpc_binding() routine. EXAMPLES The following example establishes a dced binding to a host's server configuration service. The example then obtains the UUID of some known server in order to read the server's configuration data. dced_binding_handle_t dced_bh; server_t conf; dced_string_t server_name; uuid_t srvrconf_id; error_status_t status; dced_binding_create( "srvrconf@hosts/patrick", dced_c_binding_syntax_default, &dced_bh, &status ); dced_inq_id( dced_bh, server_name, &srvrconf_id, &status ); dced_object_read( dced_bh, &srvrconf_id, (void**)&(conf), &status ); . . . RELATED INFORMATION Routines: dced_inq_name dced_binding_create dced_binding_from_rpc_binding Books: OSF DCE Application Development Guide. 5 dced_inq_name NAME dced_inq_name - Obtains the entry name that dced associates with a UUID SYNOPSIS #include void dced_inq_name( dced_binding_handle_t dced_bh, uuid_t *uuid, dced_string_t *name, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for a dced service on a specific host. uuid Specifies the UUID for which to obtain the name. Output name Returns the name associated with the uuid input. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok db_s_bad_index_type db_s_iter_not_allowed db_s_key_not_found dced_s_not_found sec_acl_invalid_permission uuid_s_bad_version DESCRIPTION The dced_inq_name() routine obtains the name associated with a UUID in a service of a specific host's dced. A name is a label for each data entry to help applications and administrators identify all data maintained by dced. The dced requires UUIDs to keep track of the data it maintains. But it also maintains a mapping of UUIDs to names so that other applications and administrators can more easily access the data by using a recognizable name rather than a cumbersome UUID. A name is a label for hostdata items, srvrconf and srvrexec servers, and keytab tables. Prior to calling this routine, the application must have established a valid dced binding handle by calling either the dced_binding_create() or dced_binding_from_rpc_binding() routine. EXAMPLES The following example establishes a dced binding handle to the local host data service, reads an entry, and uses dced_inq_name() to get the name associated with the attribute ID. dced_binding_handle_t dced_bh; uuid_t entry_uuid; sec_attr_t *data_ptr; error_status_t status; . . . dced_binding_create( dced_c_service_hostdata, dced_c_binding_syntax_default, &dced_bh, &status ); dced_hostdata_read( dced_bh, &entry_uuid, &dced_g_uuid_fileattr, &data_ptr, &status ); dced_inq_name( dced_bh, data_ptr->sec_attr.attr_id, &name, &status ); . . . RELATED INFORMATION Routines: dced_inq_id dced_binding_create dced_binding_from_rpc_binding Books: OSF DCE Application Development Guide. 4 Generic_Routines_To_Read_Data_Objects These routines obtain the actual data for items to which entries refer (objects). dced_object_read Reads one data item of a dced service, based on the entry UUID dced_object_read_all Reads all the data of a dced service's entry list dced_objects_release Releases the resources allocated for data obtained 5 dced_object_read NAME dced_object_read - Reads a data item of a dced service on a specific host SYNOPSIS #include void dced_object_read( dced_binding_handle_t dced_bh, uuid_t *entry_uuid, void **data, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for a dced service on a specific host. entry_uuid Specifies the UUID of the dced service's data entry associated with the data item. Output data Returns the data read. The data returned is one of the following structures, depending on the service: Service Data Type Returned _____________________________ hostdata sec_attr_t srvrconf server_t srvrexec server_t keytab dced_key_list_t status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok db_s_bad_index_type db_s_key_not_found dce_cf_e_file_open dce_cf_e_no_match dce_cf_e_no_mem dced_s_bad_binding dced_s_need_privacy dced_s_no_memory dced_s_no_support dced_s_not_found rpc_s_binding_has_no_auth rpc_s_invalid_binding rpc_s_wrong_kind_of_binding sec_acl_invalid_permission sec_key_mgmt_e_authn_invalid sec_key_mgmt_e_key_unavailable sec_key_mgmt_e_unauthorized uuid_s_bad_version DESCRIPTION The dced_object_read() routine reads the data for a specified entry of a dced service. When the application is done with the data, it should call the dced_objects_release() routine with a value of 1 for the count parameter. The valid services for which you can read data include hostdata, srvrconf, srvrexec, and keytab. These host services each have a list of data entries maintained by dced. The entries do not contain the actual data but contain the data's identity and an indicator of the location of the data item. The hostdata service also has the dced_hostdata_read() routine to read data, and the keytab service has a series of routines that traverse over the keys in a key table. (See the dced_keytab_initialize_cursor() routine.) The secval and endpoint services do not have data items to read with this routine. Applications can also read the data for all entries of a service using one call to dced_objects_read_all(). Prior to reading the actual data, an application commonly obtains the entries to read using the series of cursor routines that begin with dced_entry_initialize_cursor(). Prior to calling the dced_object_read() routine, the application must have established a valid dced binding handle by calling either the dced_binding_create() or dced_binding_from_rpc_binding() routine. EXAMPLES The following example creates a dced binding to a dced service based on a service type and host in an rpc binding handle. The example then obtains the service's entry list and reads the data associated with each entry. dced_binding_from_rpc_binding( service_type, rpc_bh, &dced_bh, &status ); dced_list_get( dced_bh, &entries, &status ); for(i=0; i void dced_object_read_all( dced_binding_handle_t dced_bh, unsigned32 *count, void **data_list, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for a dced service on a specific host. Output count Returns the count of the number of data items read. data_list Returns the list of data items read. The data returned is an array of one of the following types, depending on the service: Service Data Type of Array Returned ______________________________________ hostdata sec_attr_t srvrconf server_t srvrexec server_t keytab dced_key_list_t status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok db_s_bad_index_type db_s_key_not_found dce_cf_e_file_open dce_cf_e_no_match dce_cf_e_no_mem dced_s_bad_binding dced_s_need_privacy dced_s_no_memory dced_s_no_support dced_s_not_found rpc_s_binding_has_no_auth rpc_s_invalid_binding rpc_s_wrong_kind_of_binding sec_acl_invalid_permission sec_key_mgmt_e_authn_invalid sec_key_mgmt_e_key_unavailable sec_key_mgmt_e_unauthorized sec_s_no_memory uuid_s_bad_version DESCRIPTION The dced_object_read_all() routine reads all the data for a specified host service on a specific host. When the application is done with the data, it should call the dced_objects_release() routine. Applications can also read individual data objects for a service using the dced_object_read() routine. The valid services for which you can read data include hostdata, srvrconf, srvrexec, and keytab. Prior to calling the dced_object_read_all() routine, the application must have established a valid dced binding handle by calling either the dced_binding_create() or dced_binding_from_rpc_binding() routine. EXAMPLES The following example reads and displays all the data for a particular dced service. dced_binding_handle_t dced_bh; dced_string_t host_service; void *data_list; unsigned32 count; error_status_t status; dced_binding_create( host_service, dced_c_binding_syntax_default, &dced_bh, &status ); dced_object_read_all( dced_bh, &count, &data_list, &status ); display( host_service, count, &data_list ); /* app. specific */ dced_objects_release( dced_bh, count, data_list, &status ); dced_binding_free( dced_bh, &status ); RELATED INFORMATION Routines: dced_objects_release dced_object_read dced_binding_create dced_binding_from_rpc_binding Books: OSF DCE Application Development Guide. 5 dced_objects_release NAME dced_objects_release - Releases the resources allocated for data read from a dced service SYNOPSIS #include void dced_objects_release( dced_binding_handle_t dced_bh, unsigned32 count, void *data, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for a dced service on a specific host. count Specifies the number of data items previously read and now to be released. Input/Output data Specifies the data for which resources are released. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok dced_s_bad_binding dced_s_no_support DESCRIPTION The dced_objects_release() routine releases the resources allocated when data for dced is read. Applications should call dced_objects_release() when finished with data allocated by the following dced API routines: + dced_object_read_all() + dced_object_read() + dced_hostdata_read() If the data being released was read by using dced_object_read_all(), the count returned from this routine is used as input to the dced_objects_release() routine. If the data being released was read by using dced_object_read() or dced_hostdata_read(), the count value required as input for the dced_objects_release() routine is 1. EXAMPLES In the following example, a binding is created to a dced service on some host for a service that stores data, and the service's entry list is obtained. For each entry, the data is read, displayed, and released. dced_binding_handle_t dced_bh; dced_entry_list_t entries; unsigned32 i; void *data; error_status_t status; dced_binding_create( host_service, dced_c_binding_syntax_default, &dced_bh, &status ); dced_list_get( dced_bh, &entries, &status ); for(i=0; i void dced_hostdata_create( dced_binding_handle_t dced_bh, dced_entry_t *entry, dced_attr_list_t *data, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for the host data service on a specific host. Input/Output entry Specifies the hostdata entry to create. You supply a name (entry->name), description (entry->description), and file name (entry->storage_tag), in the form of dced strings. You can supply a UUID (entry->id) for dced to use or you can use a NULL value and dced will generate a new UUID for the entry. Input data Specifies the data created and written to a file on the host. The dced_attr_list_t consists of a count of the number of attributes, and an array of attributes of type sec_attr_t. The reference OSF implementation has one attribute for a hostdata item (file contents). However some vendors may provide multiple attributes. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok db_s_key_not_found db_s_readonly db_s_store_failed dced_s_already_exists dced_s_bad_binding dced_s_cant_open_storage_file dced_s_import_already_exists dced_s_unknown_attr_type sec_acl_invalid_permission DESCRIPTION The dced_hostdata_create() routine creates a new host data item in a file on the host to which the dced binding handle refers, and it generates the associated hostdata entry in the host's dced. If data that you want to add to the host data service already exists on the host (in a file), you can add it to the service by calling dced_entry_add(), which only creates the new data entry for dced. Prior to calling the dced_hostdata_create() routine, the application must have established a valid dced binding handle to the hostdata service by calling either the dced_binding_create() or dced_binding_from_rpc_binding() routine. EXAMPLES The following example creates a binding to the host data service on the local host, creates the entry data, and fills in the data structure for one attribute to a hypothetical printer configuration. The attribute represents a plain-text file containing one string of data. dced_binding_handle_t dced_bh; error_status_t status; dced_entry_t entry; dced_attr_list_t data; int num_strings, str_size; sec_attr_enc_str_array_t *attr_array; dced_binding_create( dced_c_service_hostdata, dced_c_binding_syntax_default, &dced_bh, &status ); /*Create an Entry. */ uuid_create(&entry.id, &status); entry.name = (dced_string_t)("NEWERprinter"); entry.description = (dced_string_t) ("Configuration for a new printer."); entry.storage_tag = (dced_string_t)("/etc/NEWprinter"); /* create the attributes */ data.count = 1; num_strings = 1; data.list = (sec_attr_t *) malloc( data.count * sizeof(sec_attr_t) ); data.list->attr_id = dced_g_uuid_fileattr; data.list->attr_value.attr_encoding = sec_attr_enc_printstring_array; str_size = sizeof(sec_attr_enc_str_array_t) + num_strings * sizeof(sec_attr_enc_printstring_p_t); attr_array = (sec_attr_enc_str_array_t *)malloc(str_size); data.list->attr_value.tagged_union.string_array = attr_array; attr_array->num_strings = num_strings; attr_array->strings[0] = (dced_string_t) ("New printer configuration data"); dced_hostdata_create( dced_bh, &entry, &data, &status ); dced_binding_free( dced_bh, &status ); RELATED INFORMATION Routines: dced_entry_add dced_hostdata_read dced_binding_create dced_binding_from_rpc_binding Books: OSF DCE Application Development Guide. 5 dced_hostdata_read NAME dced_hostdata_read - Reads a hostdata item maintained by dced on a specific host SYNOPSIS #include void dced_hostdata_read( dced_binding_handle_t dced_bh, uuid_t *entry_uuid, uuid_t *attr_uuid, sec_attr_t **data, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for the hostdata service on a specific host. entry_uuid Specifies the hostdata entry UUID associated with the data to read. attr_uuid Specifies the UUID associated with an attribute of the data. The attribute is either plain text (dced_g_uuid_fileattr) or binary (dced_g_uuid_binfileattr). Some vendors may allow other attributes. Output data Returns the data for the item. See the sec_intro reference page for details on the sec_attr_t data type. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok db_s_bad_index_type db_s_key_not_found dce_cf_e_file_open dce_cf_e_no_match dce_cf_e_no_mem dced_s_bad_binding dced_s_cant_open_storage_file dced_s_invalid_attr_type dced_s_no_memory sec_acl_invalid_permission uuid_s_bad_version DESCRIPTION The dced_hostdata_read() routine returns a hostdata item maintained by dced on a specific host. The standard data items include the cell name, a list of cell aliases, the host name, a list of UUID- program pairs (post_processors), and the DCE configuration database, among other items. For programming convenience, the following global variables are defined for the entry_uuid of some standard data items: dced_g_uuid_cell_name dced_g_uuid_cell_aliases dced_g_uuid_host_name dced_g_uuid_hostdata_post_proc dced_g_uuid_dce_cf_db dced_g_uuid_pe_site dced_g_uuid_svc_routing Other host-specific data items may also be maintained by the hostdata service. The UUIDs for these are established when the data item is created (See dced_hostdata_create()). After the applications reads host data and when it is done with the data, it should call the dced_objects_release() routine to release the resources allocated. Each hostdata item for a specific host is stored in a local file. The name of an item's storage file is indicated in the storage tag field of each dced hostdata entry. You can also use the dced_object_read() routine to read the text of a hostdata item. You might use this routine if your application needs to read data for other host services (srvrconf, srvrexec, or keytab) in addition to data for the hostdata service. Prior to calling the dced_hostdata_read() routine, the application must have established a valid dced binding handle to the hostdata service by calling either the dced_binding_create() or dced_binding_from_rpc_binding() routine. RELATED INFORMATION Routines: dced_objects_release dced_object_read dced_binding_create dced_binding_from_rpc_binding Books: OSF DCE Application Development Guide. 5 dced_hostdata_write NAME dced_hostdata_write - Replaces an existing hostdata item maintained by dced on a specific host SYNOPSIS #include void dced_hostdata_write( dced_binding_handle_t dced_bh, uuid_t *entry_uuid, dced_attr_list_t *data, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for the Host Data service on a specific host. entry_uuid Specifies the hostdata entry UUID to associate with the data to be written. data Specifies the data to write. The dced_attr_list_t consists of a count of the number of attributes, and an array of attributes of type sec_attr_t. The reference OSF implementation has one attribute for a hostdata item (file contents). However some vendors may require multiple attributes. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok db_s_bad_index_type db_s_key_not_found dced_s_bad_binding dced_s_cant_open_storage_file dced_s_no_postprocessors dced_s_postprocessor_file_fail dced_s_postprocessor_spawn_fail dced_s_unknown_attr_type sec_acl_invalid_permission uuid_s_bad_version DESCRIPTION The dced_hostdata_write() routine replaces existing data for a hostdata item maintained by dced on a specific host. If the entry_uuid is not one maintained be dced, an error is returned and a new entry is not created. Use dced_hostdata_create() to create a new entry. Prior to calling the dced_hostdata_write() routine, the application must have established a valid dced binding handle to the hostdata service by calling either the dced_binding_create() or dced_binding_from_rpc_binding() routine. RELATED INFORMATION Routines: dced_hostdata_read dced_hostdata_create dced_binding_create dced_binding_from_rpc_binding Books: OSF DCE Application Development Guide. 5 dced_hostdata_delete NAME dced_hostdata_delete - Deletes a hostdata item from a specific host and removes the associated entry from dced SYNOPSIS #include void dced_hostdata_delete( dced_binding_handle_t dced_bh, uuid_t *entry_uuid, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for the hostdata service on a specific host. entry_uuid Specifies the UUID of the hostdata entry (and associated data) to delete. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok db_s_bad_index_type db_s_del_failed db_s_iter_not_allowed db_s_key_not_found dced_s_bad_binding dced_s_cant_remove_storage_file dced_s_not_found sec_acl_invalid_permission DESCRIPTION The dced_hostdata_delete() routine deletes a hostdata item (a file) from a specific host, and removes the associated entry from the host data service of that host's dced. If you want to only make the data inaccessible remotely but not delete it, use the dced_entry_remove() routine which only removes the data's hostdata entry. Prior to calling the dced_hostdata_delete() routine, the application must have established a valid dced binding handle for the hostdata service by calling either the dced_binding_create() or dced_binding_from_rpc_binding() routine. WARNINGS Do not delete the standard hostdata items such as cell_name, cell_aliases, host_name, post_processors, or dce_cf.db. This will cause operational problems for the host. RELATED INFORMATION Routines: dced_entry_remove dced_hostdata_read dced_binding_create dced_binding_from_rpc_binding Books: OSF DCE Application Development Guide. 4 Server_Configuration_Control_Routines dced_server_create Creates a DCE server's configuration data dced_server_modify_attributes Modifies a DCE server's configuration data dced_server_delete Deletes a DCE server's configuration data dced_server_start Starts a DCE-configured server 5 dced_server_create NAME dced_server_create - Creates a DCE server's configuration data for the host's dced SYNOPSIS #include void dced_server_create( dced_binding_handle_t dced_bh, server_t *conf_data, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for the srvrconf service on a specific host. Input/Output conf_data Specifies the configuration data for the server. The dced_intro reference page describes the server_t structure. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok db_s_bad_header_type db_s_bad_index_type db_s_iter_not_allowed db_s_key_not_found db_s_readonly db_s_store_failed dced_s_already_exists dced_s_bad_binding dced_s_name_missing sec_acl_invalid_permission DESCRIPTION The dced_server_create() routine creates a server's configuration data. This routine is used by management installation applications to remotely (or locally) establish the data used to control how a DCE server starts. However, it does not create the program or start it. Since this activity is typically part of a server's installation, you can also use dcecp's server create operation. Management applications use the dced_object_read() routine to read the configuration data. Prior to calling dced_server_create(), the application must have established a valid dced binding handle to the srvrconf service by calling either dced_binding_create() or dced_binding_from_rpc_binding(). EXAMPLES The following example shows how to fill in some of the fields of a server_t structure and then create the configuration in dced. dced_binding_handle_t dced_bh; server_t conf; error_status_t status; dced_binding_create( "srvrconf@hosts/katharine", dced_c_binding_syntax_default, &dced_bh, &status ); /* setup a server_t structure */ uuid_create(&conf.id, &status); conf.name = (dced_string_t)"application"; conf.entryname = (dced_string_t)"/.:/development/new_app"; conf.services.count = 1; /* service_t structure(s) */ conf.services.list = malloc( conf.services.count * sizeof(service_t) ); rpc_if_inq_id( application_v1_0_c_ifspec, &(conf.services.list[0].ifspec), &status ); conf.services.list[0].ifname = (dced_string_t)"application"; conf.services.list[0].annotation = (dced_string_t)"A new application"; conf.services.list[0].flags = 0; /* server_fixedattr_t structure */ conf.fixed.startupflags = server_c_startup_explicit | server_c_startup_on_failure; conf.fixed.flags = 0; conf.fixed.program = (dced_string_t)"/usr/users/bin/new_app"; dced_server_create( dced_bh, &conf, &status ); . . . RELATED INFORMATION Routines: dced_object_read dced_binding_create dced_binding_from_rpc_binding dcecp objects: server Books: OSF DCE Application Development Guide. 5 dced_server_modify_attributes NAME dced_server_modify_attributes - Modifies attributes for a DCE server's configuration data SYNOPSIS #include void dced_server_modify_attributes( dced_binding_handle_t dced_bh, uuid_t *conf_uuid, dced_attr_list_t *data, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for the srvrconf service on a specific host. conf_uuid Specifies the UUID that dced uses to identify a server's configuration data to be modified. data Specifies the attributes to be modified. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok db_s_bad_index_type db_s_iter_not_allowed db_s_readonly db_s_store_failed dced_s_bad_binding dced_s_not_found sec_acl_invalid_permission DESCRIPTION The dced_server_modify_attributes() routine replaces a server's attributes of its configuration data maintained by dced on a specific host. This routine is typically called after a configuration is created with the dced_server_create() routine. A server's configuration is manipulated in a server_t data structure, and the dced_server_modify_attributes() routine affects only the attributes member of this structure. To change other server configuration data, you must first delete the configuration by using dced_server_delete() and then create the configuration again by using dced_server_create(). Prior to calling dced_server_modify_attributes(), the application must have established a valid dced binding handle to the srvrconf service by calling either dced_binding_create() or dced_binding_from_rpc_binding(). RELATED INFORMATION Routines: dced_object_read dced_binding_create dced_binding_from_rpc_binding dcecp Objects: server Books: OSF DCE Application Development Guide 5 dced_server_delete NAME dced_server_delete - Deletes a DCE server's configuration data from dced SYNOPSIS #include void dced_server_delete( dced_binding_handle_t dced_bh, uuid_t *conf_uuid, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for the srvrconf service on a specific host. conf_uuid Specifies the UUID that dced uses to identify the server's configuration data to be deleted. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok db_s_bad_index_type db_s_del_failed db_s_iter_not_allowed dced_s_bad_binding dced_s_not_found sec_acl_invalid_permission DESCRIPTION The dced_server_delete() routine deletes a server's configuration data from the server's dced. This routine removes a server from DCE control by making it incapable of starting via dced. It does not delete the program from disk nor does it affect the server if it is currently running. Prior to using dced_server_delete(), the server configuration data must be created by an administrator using the dcecp server create operation or by an application that using dced_server_create(). Prior to calling dced_server_delete(), the application must have established a valid dced binding handle to the srvrconf service by calling either dced_binding_create() or dced_binding_from_rpc_binding(). EXAMPLES In the following example, a dced binding is created to the server configuration service on a host, and then an inquiry is made as to the UUID associated with a particular server. The dced_server_delete() routine is then used to delete the configuration. dced_binding_handle_t dced_bh; dced_string_t server_name; uuid_t srvrconf_id; error_status_t status; name_server( &server_name ); /* application specific */ dced_binding_create( "srvrconf@hosts/katharine", dced_c_binding_syntax_default, &dced_bh, &status ); dced_inq_id( dced_bh, server_name, &srvrconf_id, &status ); dced_server_delete( dced_bh, &srvrconf_id, &status ); dced_binding_free( dced_bh, &status ); RELATED INFORMATION Routines: dced_server_create dced_server_modify_attributes dced_binding_create dced_binding_from_rpc_binding dcecp Objects: server Books: OSF DCE Application Development Guide. 5 dced_server_start NAME dced_server_start - Starts a DCE-configured server on a specified host SYNOPSIS #include void dced_server_start( dced_binding_handle_t dced_bh, uuid_t *conf_uuid, dced_attr_list_t *attributes, uuid_t *exec_uuid, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for the srvrconf service on a specific host. conf_uuid Specifies the UUID that dced uses to identify the server to start. If the value input is that of a server that is already running, dced starts a new instance. attributes Specifies the configuration attributes to use to start the server. If the value is NULL, the default configuration defined in dced is used. Input/Output exec_uuid Specifies a new UUID for dced to use to identify the running server. If a NIL UUID is input, a new UUID is created and returned. If the value input is that of a server that is already running, dced starts a new instance and returns a new value. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok db_s_bad_header_type db_s_iter_not_allowed db_s_key_not_found db_s_readonly db_s_store_failed dced_s_bad_binding dced_s_no_support dced_s_not_found dced_s_sc_cant_fork dced_s_sc_invalid_attr_type dced_s_sc_open_file_failed sec_acl_invalid_permission uuid_s_bad_version DESCRIPTION The dced_server_start() routine starts DCE-configured servers on a specific remote host (or the local host). The configuration data is stored in an object in the srvrconf service of dced. When the server starts, dced uses the server configuration object and creates a server execution object in the srvrexec service. A server execution object consists of data that describes the executing server. Management applications create the configuration data by using the dced_server_create() use the dced_object_read() routine to read the configuration or execution data. Prior to calling dced_server_start(), the application must have established a valid dced binding handle to the srvrconf service by calling either dced_binding_create() or dced_binding_from_rpc_binding(). EXAMPLES The following example starts a configured server using a nil UUID as input for the executing server. dced_binding_handle_t conf_bh; dced_string_t server_name; uuid_t srvrconf_id, srvrexec_id; error_status_t status; dced_binding_create( "srvrconf@hosts/patrick", dced_c_binding_syntax_default, &conf_bh, &status ); dced_inq_id( conf_bh, server_name, &srvrconf_id, &status ); uuid_create_nil( &srvrexec_id, &status ); dced_server_start( conf_bh, &srvrconf_id, NULL, &srvrexec_id, &status ); . . . RELATED INFORMATION Routines: dced_server_create dced_server_stop dced_binding_create dced_binding_from_rpc_binding Commands: server Books: OSF DCE Application Development Guide. 4 Server_Execution_Control_Routines dced_server_disable_if Disables a service provided by a server dced_server_enable_if Re-enables a service provided by a server dced_server_stop Stops a DCE-configured server 5 dced_server_disable_if NAME dced_server_disable_if - Disables a service (rpc interface) provided by a specific server on a specific host SYNOPSIS #include void dced_server_disable_if( dced_binding_handle_t dced_bh, uuid_t *exec_uuid, rpc_if_id_t *interface, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for the srvrexec service on a specific host. exec_uuid Specifies the UUID that dced uses to identify the running server. interface Specifies the RPC interface identifier that represents the service to be disabled. The interface identifier is generated when idl compiles an interface definition file. The interface identifier is an rpc_if_id_t structure that contains the interface UUID (uuid) of type uuid_t, and numbers of type unsigned16 representing the major (vers_major) and minor (vers_minor) version numbers for the interface. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok db_s_bad_index_type db_s_iter_not_allowed db_s_readonly db_s_store_failed dced_s_bad_binding dced_s_not_found sec_acl_invalid_permission DESCRIPTION The dced_server_disable_if() routine disables a service provided by a server on a specific host. A service is represented by an RPC interface identifier. Management applications use this routine to remotely disable an interface so it is inaccessible by clients, without completely stopping the entire server. When a server starts and initializes itself, it must call the dce_server_register() routine to enable all of its services. The server can then disable its own individual services by using dce_server_disable_service(). This routine unregisters the service's interface from the RPC runtime and marks the interface as disabled in the endpoint map. As an alternative, a management application can use dced_server_disable_if() to disable individual services. However, this routine only affects the endpoint map in dced by marking the interface as disabled and does not affect the server's runtime. A management application can re-enable a service again by calling the dced_server_enable_if() routine. (Servers re-enable their own services using the dce_server_enable_if() routine.) Prior to calling dced_server_disable_if(), the application must have established a valid dced binding handle to the srvrexec service by calling either dced_binding_create() or dced_binding_from_rpc_binding(). RELATED INFORMATION Routines: dce_server_register dce_server_disable_if dce_server_enable_if dced_server_enable_if dced_binding_create dced_binding_from_rpc_binding dcecp Objects: server Books: OSF DCE Application Development Guide. 5 dced_server_enable_if NAME dced_server_enable_if - Enables a service (rpc interface) of a specific server on a specific host SYNOPSIS #include void dced_server_enable_if( dced_binding_handle_t dced_bh, uuid_t *exec_uuid, rpc_if_id_t *interface, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for the srvrexec service on a specific host. exec_uuid Specifies the UUID that dced uses to identify the running server. interface Specifies the RPC interface identifier that represents the service to be enabled. The interface identifier is generated when idl compiles an interface definition file. The interface identifier is a structure that contains the interface UUID (interface->uuid), and the major (interface->vers_major) and minor (interface->vers_minor) version numbers for the interface. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok db_s_bad_index_type db_s_iter_not_allowed db_s_readonly db_s_store_failed dced_s_bad_binding dced_s_not_found sec_acl_invalid_permission DESCRIPTION The dced_server_enable_if() routine enables a service (or re-enables a previously disabled service) that a specific server provides. Management applications use this routine. A service is represented by an RPC interface identifier. When a server starts and initializes itself, it typically calls the dce_server_register() routine to enable all of its services. The services can then be disabled and re-enabled, as needed. A server enables and disables its own services by using dce_server_enable_service() and dce_server_disable_service() and a management application enables and disables a remote server's service using dced_server_enable_if() and dced_server_disable_if(). The dce_server* routines affect both the RPC runtime and the local endpoint map by registering (or unregistering) with the runtime and setting a flag for the interface in the the endpoint map as enabled (or disabled). The dced_server_enable_if() and dced_server_disable_if() routines affect only the remote endpoint map by setting the flag. Prior to calling dced_server_enable_if(), the application must have established a valid dced binding handle to the srvrexec service by calling either dced_binding_create() or dced_binding_from_rpc_binding(). RELATED INFORMATION Routines: dce_server_register dce_server_enable_if dce_server_disable_if dced_server_disable_if dced_binding_create dced_binding_from_rpc_binding dcecp Objects: server Books: OSF DCE Application Development Guide. 5 dced_server_stop NAME dced_server_stop - Stops a DCE-configured server running on a specific host SYNOPSIS #include void dced_server_stop( dced_binding_handle_t dced_bh, uuid_t *exec_uuid, srvrexec_stop_method_t method, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for the srvrexec service on a specific host. exec_uuid Specifies a UUID that dced uses to identify the running server. If the value input is dced_g_uuid_all_servers, then dced attempts to stop all the DCE servers running on that host. method Specifies the method dced uses to stop a server. A method is represented by one of the following values: srvrexec_stop_rpc Uses the rpc_mgmt_stop_server_listening routine. This is the cleanest way to stop a server because it waits for outstanding remote procedure calls to finish before making the server's rpc_server_listen() routine return. srvrexec_stop_soft Uses a "soft" local host mechanism (such as the TERM signal in UNIX) srvrexec_stop_hard Uses a "hard" local host mechanism (such as the KILL signal in UNIX) srvrexec_stop_error Uses a mechanism that saves the program state (such as the ABORT signal in UNIX) Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok dced_s_bad_binding dced_s_no_support dced_s_not_found rpc_s_binding_incomplete rpc_s_comm_failure rpc_s_invalid_binding rpc_s_mgmt_op_disallowed rpc_s_unknown_if rpc_s_wrong_kind_of_binding sec_acl_invalid_permission uuid_s_bad_version DESCRIPTION The dced_server_stop() routine stops DCE-configured servers on specific hosts. When the server is completely stopped and no longer a running process, dced deletes the associated execution data it maintained. Administrators use the dcecp operations server create and server start to configure and start a server, and management applications use the associated dced_server_create() and dced_server_start() routines. Prior to calling dced_server_stop(), the application must have established a valid dced binding handle to the srvrexec service by calling either dced_binding_create() or dced_binding_from_rpc_binding(). CAUTIONS Using the value dced_g_uuid_all_servers for the exec_uuid parameter causes dced to shutdown all servers including itself. EXAMPLES The following example obtains dced binding handles to the server configuration and execution services of dced on the host patrick. The example then checks to see if the server is running by seeing if dced has a UUID and entry for the executing server. However, the server may be in the process of starting up or stopping, so the example also checks to be sure the instance UUID of the running server matches the UUID of the configuration for that server. If there is a match, the server is running. Finally, the example stops the server by calling dced_server_stop() with the srvrexec_stop_rpc parameter. dced_binding_handle_t conf_bh, exec_bh; dced_string_t server_name; void *data; server_t *exec_ptr; uuid_t srvrconf_id, srvrexec_id; error_status_t status; . . . dced_binding_create( "srvrconf@hosts/patrick", dced_c_binding_syntax_default, &conf_bh, &status ); dced_binding_create( "srvrexec@hosts/patrick", dced_c_binding_syntax_default, &exec_bh, &status) ; /* is server running? */ dced_inq_id( exec_bh, server_name, &srvrexec_id, &status ); /* also check to be sure server is not coming up or going down */ dced_object_read( exec_bh, &srvrexec_id, &data, &status ); exec_ptr = (server_t*)data; dced_inq_id( conf_bh, server_name, &srvrconf_id, &status ); if (uuid_equal( &srvrconf_id, &exec_ptr->exec_data.tagged_union.running_data.instance, &status) ) { dced_server_stop( exec_bh, &srvrexec_id, srvrexec_stop_rpc, &status ); } dced_objects_release( exec_bh, 1, data, &status ); dced_binding_free( conf_bh, &status ); dced_binding_free( exec_bh, &status ); RELATED INFORMATION Routines: dced_server_create dced_server_start rpc_mgmt_stop_server_listening dced_binding_create dced_binding_from_rpc_binding dcecp Objects: server Books: OSF DCE Application Development Guide. 4 Security_Validation_Routines dced_secval_start Starts a host's security validation service dced_secval_validate Validates that the DCE Security daemon (secd) used by a specific host is legitimate dced_secval_status Returns a status parameter of TRUE if the security validation service is activated and FALSE if not dced_secval_stop Stops a host's security validation service 5 dced_secval_start NAME dced_secval_start - Starts the security validation service of a specific host's dced SYNOPSIS #include void dced_secval_start( dced_binding_handle_t dced_bh, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for the secval service on a specific host. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok dced_s_bad_binding dced_s_sv_already_enabled sec_acl_invalid_permission DESCRIPTION The dced_secval_start() routine starts the Security Validation service of a specific host's dced. This routine is typically used by management applications. The Security Validation service (secval) has two major functions: 1. Maintain a login context for the host's self identity. 2. Validate and certify to applications (usually login programs) that the DCE Security daemon (secd) is legitimate. The secval is commonly started by default when dced starts. See the dced_secval_stop() routine for a discussion of when to use the combination of dced_secval_stop() and dced_secval_start(). Prior to calling this routine, the application must have established a valid dced binding handle to the secval service by calling either the dced_binding_create() or dced_binding_from_rpc_binding() routine. RELATED INFORMATION Routines: dced_secval_stop dced_binding_create dced_binding_from_rpc_binding Commands: dced The secval object of dcecp Books: OSF DCE Application Development Guide. 5 dced_secval_validate NAME dced_secval_validate - Validates that the secd used by a specific host is legitimate SYNOPSIS #include void dced_secval_validate( dced_binding_handle_t dced_bh, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for the secval service on a specific host. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok dced_s_bad_binding ept_s_not_registered rpc_s_comm_failure rpc_s_invalid_binding rpc_s_rpcd_comm_failure rpc_s_wrong_kind_of_binding sec_login_s_no_current_context DESCRIPTION The dced_secval_validate() routine validates and certifies for a specific host that the DCE Security daemon (secd) is legitimate. Typically, a login program uses the security validation service when it uses the Security Service's Login API (routines that begin with sec_login). However, if a management application trusts some remote host, it can use dced_secval_validate() to validate secd, without logging in to the host. RELATED INFORMATION Routines: sec_login* API dced_secval_start dced_binding_create dced_binding_from_rpc_binding Commands: dced The secval object of dcecp Books: OSF DCE Application Development Guide. 5 dced_secval_status NAME dced_secval_status - Indicates whether or not a specific host's security validation service of dced is running SYNOPSIS #include void dced_secval_status( dced_binding_handle_t dced_bh, boolean32 *secval_active, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for the secval service on a specific host. Output secval_active Returns a value of TRUE if the security validation service is running and FALSE if it is not running. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok dced_s_bad_binding DESCRIPTION The dced_secval_status() routine sets a parameter to TRUE or FALSE depending on whether the security validation service has been activated or deactivated. Prior to calling this routine, the application must have established a valid dced binding handle to the secval service by calling either the dced_binding_create() or dced_binding_from_rpc_binding() routine. RELATED INFORMATION Routines: dced_secval_start dced_secval_stop dced_binding_create dced_binding_from_rpc_binding Commands: dced the secval object of dcecp Books: OSF DCE Application Development Guide. 5 dced_secval_stop NAME dced_secval_stop - Stops the security validation service of a specific host's dced SYNOPSIS #include void dced_secval_stop( dced_binding_handle_t dced_bh, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for the secval service on a specific host. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok dced_s_bad_binding dced_s_sv_not_enabled sec_acl_invalid_permission DESCRIPTION The dced_secval_stop() routine stops the security validation service (secval) of a specific host's dced. This routine is typically used by managment applications. The secval service is commonly started by default when dced starts. The main use of dced_secval_stop() and dced_secval_start() is to force a refresh of the host principal credentials. This is the only way to force certain registry changes made by the host principal (such as groupset membership) to be seen by processes running on the host. You can easily stop and then start the secval service with the following operations: dcecp -c secval deactivate dcecp -c secval activate It is not a good idea to remove the machine principal self credentials for an extended period of time because processes running as self will fail in their attempts to perform authenticated operations. RELATED INFORMATION Routines: dced_secval_start dced_binding_create dced_binding_from_rpc_binding Commands: dced The secval object of dcecp Books: OSF DCE Application Development Guide. 4 Key_Table_Management_Routines dced_keytab_create Creates a key table with a list of keys in a new file dced_keytab_delete Deletes a key table file and removes the associated entry dced_keytab_initialize_cursor Obtains a list of keys from a key table and sets a cursor at the beginning of the list dced_keytab_get_next_key Returns a key from a cached list, and advances the cursor dced_keytab_release_cursor Releases the resources associated with a cursor that traverses a key table dced_keytab_add_key Adds a key to a key table dced_keytab_change_key Changes a key in both a key table and in the security registry dced_keytab_remove_key Removes a key from a key table 5 dced_keytab_create NAME dced_keytab_create - Creates a key table with a list of keys (server passwords) in a new file on a specific host SYNOPSIS #include void dced_keytab_create( dced_binding_handle_t dced_bh, dced_entry_t *keytab_entry, dced_key_list_t *keys, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for the keytab service on a specific host. Input/Output keytab_entry Specifies the keytab entry to create for dced. keys Specifies the list of keys to be written to the key table file. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok db_s_bad_header_type db_s_bad_index_type db_s_bad_index_type db_s_iter_not_allowed db_s_key_not_found db_s_readonly db_s_store_failed dced_s_already_exists dced_s_bad_binding dced_s_import_already_exists dced_s_need_privacy rpc_s_binding_has_no_auth rpc_s_invalid_binding rpc_s_wrong_kind_of_binding sec_acl_invalid_permission sec_key_mgmt_e_authn_invalid sec_key_mgmt_e_key_unavailable sec_key_mgmt_e_key_unsupported sec_key_mgmt_e_key_version_exists sec_key_mgmt_e_unauthorized uuid_s_bad_version DESCRIPTION The dced_keytab_create() routine creates a new key table file on a specific host, and it generates the associated keytab service entry in dced. This routine is used by management applications to remotely create a key table. Servers typically create their own key table locally using the sec_key_mgmt_set_key routine. However, if several servers on different hosts share the same principal, each host requires a local copy of the key table. If a key table that you want to add to the keytab service already exists on the host, you can add it to the service by calling dced_entry_add(). This routine creates a new keytab service entry by associating the existing key table file with a new UUID in dced. Prior to calling the dced_keytab_create() routine, the application must have established a valid dced binding handle to the keytab service by calling either the dced_binding_create() or dced_binding_from_rpc_binding() routine. RELATED INFORMATION Routines: sec_key_mgmt_set_key dced_entry_add dced_binding_from_rpc_binding dced_binding_create Books: OSF DCE Application Development Guide. 5 dced_keytab_delete NAME dced_keytab_delete - Deletes a key table file from a specific host SYNOPSIS #include void dced_keytab_delete( dced_binding_handle_t dced_bh, uuid_t *keytab_uuid, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for the keytab service on a specific host. keytab_uuid Specifies the UUID of the keytab entry and associated key table to be deleted. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok db_s_bad_index_type db_s_del_failed db_s_iter_not_allowed db_s_key_not_found dced_s_bad_binding dced_s_cant_remove_storage_file dced_s_need_privacy rpc_s_binding_has_no_auth rpc_s_invalid_binding rpc_s_wrong_kind_of_binding sec_acl_invalid_permission DESCRIPTION The dced_keytab_delete() routine deletes a key table (file) from a specific host and removes the associated entry from the keytab service of that host's dced. A key table is a file containing a list of server keys (passwords). This routine is used by management applications to remotely delete a key table. To remove individual keys from a remote key table, use the dced_keytab_remove_key() routine. If you want to only make the key table inaccessible remotely (via dced) but not delete it, use the dced_entry_remove() routine. This routine only removes the key table's keytab entry from dced. Prior to calling the dced_keytab_delete() routine, the application must have established a valid dced binding handle to the keytab service by calling either the dced_binding_create() or dced_binding_from_rpc_binding() routine. RELATED INFORMATION Routines: dced_keytab_remove_key dced_entry_remove dced_binding_create dced_binding_from_rpc_binding Books: OSF DCE Application Development Guide. 5 dced_keytab_initialize_cursor NAME dced_keytab_initialize_cursor - Obtains a list of keys from a key table and sets a cursor at the beginning of the list SYNOPSIS #include void dced_keytab_initialize_cursor( dced_binding_handle_t dced_bh, uuid_t *keytab_uuid, dced_keytab_cursor_t *cursor, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for the keytab service on a specific host. keytab_uuid Specifies the keytab entry dced associates with a key table. Output cursor Returns the cursor that is used to traverse the list of keys. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok dced_s_bad_binding dced_s_need_privacy dced_s_no_memory dced_s_no_support sec_acl_invalid_permission sec_key_mgmt_e_authn_invalid sec_key_mgmt_e_unauthorized DESCRIPTION The dced_keytab_initialize_cursor() routine obtains the complete list of keys from a remote key table and sets a cursor at the beginning of the cached list keys. In order to minimize the security risks of keys exposed to the network, the entire set of keys are encrypted and transferred in one remote procedure call rather than individually or in chunks. The cursor is then used in subsequent calls to dced_keytab_get_next_key() to obtain individual keys. When the application is finished traversing the key list, it should call dced_keytab_release_cursor() to release the resources previously allocated. Management applications use dced_keytab_initialize_cursor() and its associated routines to remotely access server keys. Servers use sec_key_mgmt_initialize_cursor and its associated routines to manage their own keys locally. Prior to calling the dced_keytab_initialize_cursor() routine, the application must have established a valid dced binding handle to the keytab service by calling either the dced_binding_create() or dced_binding_from_rpc_binding() routine. RELATED INFORMATION Routines: dced_keytab_get_next_key dced_keytab_release_cursor sec_key_mgmt_initialize_cursor dced_binding_create dced_binding_from_rpc_binding Books: OSF DCE Application Development Guide. 5 dced_keytab_get_next_key NAME dced_keytab_get_next_key - Returns a key from a cached list, and advances the cursor in the list SYNOPSIS #include void dced_keytab_get_next_key( dced_keytab_cursor_t cursor, dced_key_t **key, error_status_t *status ); PARAMETERS Input/Output cursor Specifies the cursor that points to a key, and returns the cursor advanced to the next key in the list. Output key Returns the current key to which the cursor points. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok dced_s_no_more_entries DESCRIPTION The dced_keytab_get_next_key() routine obtains the current key to which the key-list cursor points. This routine is commonly used in a loop to traverse a key table's keys. The keys are returned in an undetermined order. Prior to using this routine in the loop, the application must call dced_keytab_initialize_cursor() to obtain the key list and established the beginning of the cursor. When the application is finished traversing the key list, it should call dced_keytab_release_cursor() to release the resources allocated. Management applications use dced_keytab_get_next_key() to remotely access a server's individual keys. Servers use sec_key_mgmt_get_next_key to access their own local keys individually. You can also use the dced_object_read() routine to read an entire key table. You might use dced_object_read() if your application needs to bind to and read data for other host services (srvrconf, srvrexec, or hostdata) in addition to data for the keytab service. RELATED INFORMATION Routines: dced_keytab_initialize_cursor dced_keytab_release_cursor sec_key_mgmt_get_next_key dced_object_read Books: OSF DCE Application Development Guide. 5 dced_keytab_release_cursor NAME dced_keytab_release_cursor - Releases the resources of a cursor that traverses a key table's list of keys (server passwords) SYNOPSIS #include void dced_keytab_release_cursor( dced_keytab_cursor_t *cursor, error_status_t *status ); PARAMETERS Input/Output cursor Specifies the cursor for which resources are released. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok dced_s_bad_binding dced_s_no_support DESCRIPTION The dced_keytab_release_cursor() routine releases the cursor and resources initially set by the dced_keytab_initialize_cursor() routine and used by the dced_keytab_get_next_key() routine. Prior to calling this routine, the application must have first established a valid dced binding handle by calling either dced_binding_create() or dced_binding_from_rpc_binding(), and then the application must have called the dced_keytab_initialize_cursor() routine. RELATED INFORMATION Routines: dced_keytab_initialize_cursor dced_keytab_get_next_key Books: OSF DCE Application Development Guide. 5 dced_keytab_add_key NAME dced_keytab_add_key - Adds a key (server password) to a specified key table on a specific host SYNOPSIS #include void dced_keytab_add_key( dced_binding_handle_t dced_bh, uuid_t *keytab_uuid, dced_key_t *key, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for the keytab service on a specific host. keytab_uuid Specifies the UUID that dced uses to identify the key table to which the key is to be added. Input/Output key Specifies the key to be added. Some fields are completed by dced. See dced_intro. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok db_s_bad_index_type db_s_key_not_found dced_s_bad_binding dced_s_key_v0_not_allowe dced_s_key_version_mismatch dced_s_need_privacy dced_s_random_key_not_allowed rpc_s_binding_has_no_auth rpc_s_invalid_binding rpc_s_wrong_kind_of_binding sec_acl_invalid_permission sec_key_mgmt_e_authn_invalid sec_key_mgmt_e_key_unavailable sec_key_mgmt_e_key_unsupported sec_key_mgmt_e_key_version_exists sec_key_mgmt_e_unauthorized DESCRIPTION The dced_keytab_add_key() routine adds a key to a server's key table (file) on a specific host, without changing the key in the security registry. (Servers use sec_key_mgmt_set_key to do this for their own local key table.) Most management applications use the dced_keytab_change_key() routine to remotely change a key because it also changes the key in the Security Registry. Managing the same key in multiple key tables is a more complex process. The Security Registry needs a copy of a server's key so that during the authentication process, it can encrypt tickets that only a server with that key can later decrypt. Part of updating a key in the Security Registry also includes automatic version number updating. When servers share the same principle identity they use the same key. If these servers are on different hosts, then the key must be in more than one key table. (Even if the servers are on the same host, it is possible for their keys to be in different key tables, although this is not a recommended key management practice.) When the same keys in different tables need changing, one (perhaps the master server or busiest one) is changed using dced_keytab_change_key() which also causes an automatic version update. However, all other copies of the key must be changed using the dced_keytab_add_key() routine so that the version number does not change again. Prior to calling dced_keytab_add_key() the application must have established a valid dced binding handle to the keytab service by calling either the dced_binding_create() or dced_binding_from_rpc_binding() routine. RELATED INFORMATION Routines: dced_keytab_change_key sec_key_mgmt_set_key dced_binding_create dced_binding_from_rpc_binding Books: OSF DCE Application Development Guide. 5 dced_keytab_change_key NAME dced_keytab_change_key - Changes a key (server password) in both a key table and in the security registry SYNOPSIS #include void dced_keytab_change_key( dced_binding_handle_t dced_bh, uuid_t *keytab_uuid, dced_key_t *key, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for the keytab service on a specific host. keytab_uuid Specifies the UUID dced uses to identify the key table in which the key is to be changed. Input/Output key Specifies the new key. Some fields are modified by dced. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok db_s_bad_index_type db_s_key_not_found dced_s_bad_binding dced_s_key_version_mismatch dced_s_need_privacy rpc_s_binding_has_no_auth rpc_s_invalid_binding rpc_s_wrong_kind_of_binding sec_acl_invalid_permission sec_key_mgmt_e_authn_invalid sec_key_mgmt_e_authn_unavailable sec_key_mgmt_e_key_unavailable sec_key_mgmt_e_key_unsupported sec_key_mgmt_e_key_version_exists sec_key_mgmt_e_not_implemented sec_key_mgmt_e_unauthorized sec_rgy_object_not_found sec_rgy_server_unavailable DESCRIPTION The dced_keytab_change_key() routine updates a key in both the key table on a specific host and in the Security Registry. Management applications change keys remotely with this routine. (Servers can change their own keys locally with the sec_key_mgmt_change_key routine.) The Security Registry needs a copy of a server's current key so that during the authentication process, it can encrypt tickets that only a server with that key can later decrypt. When a management application calls dced_keytab_change_key(), dced first tries to make the modification in the Security Registry, and, if successful it then modifies the key in the key table. The old key is not really replaced but a new version and key is established for all new authenticated communication. The old version is maintained in the key table (and Registry too) for a time so that existing clients with valid tickets can still communicate with the server. The old key is removed depending on the local cell's change policy and if the server calls sec_key_mgmt_garbage_collect() to purge its old keys explicitly, or sec_key_mgmt_manage_key() to purge them implicitly. When more than one server shares the same principal identity, they use the same key. If you need to change the same key in more than one key table, use decd_keytab_change_key() for one change and then use the dced_keytab_add_key() routine for all others. RELATED INFORMATION Routines: dced_keytab_add_key sec_key_mgmt_change_key dced_binding_create dced_binding_from_rpc_binding Books: OSF DCE Application Development Guide. 5 dced_keytab_remove_key NAME dced_keytab_remove_key - Removes a key (server password) from a specified key table on a specific host SYNOPSIS #include void dced_keytab_remove_key( dced_binding_handle_t dced_bh, uuid_t *keytab_uuid, dced_key_t *key, error_status_t *status ); PARAMETERS Input dced_bh Specifies the dced binding handle for the keytab service on a specific host. keytab_uuid Specifies the UUID dced maintains to identify the key table from which the key is to be removed. key Specifies the key to be removed from the key table. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes are: error_status_ok db_s_bad_index_type db_s_key_not_found dced_s_bad_binding dced_s_need_privacy rpc_s_binding_has_no_auth rpc_s_invalid_binding rpc_s_wrong_kind_of_binding sec_acl_invalid_permission sec_key_mgmt_e_authn_invalid sec_key_mgmt_e_key_unavailable sec_key_mgmt_e_unauthorized DESCRIPTION The dced_keytab_remove_key() routine removes a key from a key table (file) on a specific host. The key table is specified with a keytab entry UUID from the host's dced. Management applications use dced_keytab_remove_key() to remotely remove server keys from key tables. Typically, servers delete their own keys from their local key tables implicitly by calling sec_key_mgmt_manage_key, or explicitly by calling sec_key_mgmt_delete_key. Applications can delete an entire key table file using the dced_keytab_delete() routine. Prior to calling this routine, the application must have established a valid dced binding handle to the keytab service by calling either the dced_binding_create() or dced_binding_from_rpc_binding() routine. RELATED INFORMATION Routines: sec_key_mgmt_delete_key dced_keytab_delete dced_binding_create dced_binding_from_rpc_binding Books: OSF DCE Application Development Guide. 4 Data_Types_And_Structures The following data types used with the dced API are defined in dce/dced_base.idl and are shown here in alphabetical order. dced_attr_list_t This data structure specifies the configuration attributes to use when you start a server via dced. The structure consists of the following: count An unsigned32 number representing the number of attributes in the list. list An array of configuration attributes where each element is of type sec_attr_t. This data type is described in the sec_intro reference page. For dced, the list[i].attr_id field can have values of either dced_g_uuid_fileattr specifying plain text or dced_g_uuid_binfileattr specifying binary data. dced_binding_handle_t A dced binding handle is an opaque pointer that refers to information that includes a dced service (hostdata, srvrconf, srvrexec, secval, or keytab) and RPC binding information for a specific DCE Host daemon. dced_cursor_t The entry list cursor is an opaque pointer used to keep track of a location in an entry list between calls that traverse the list. dced_entry_t An entry is the structure that contains information about a data item (or object) maintained by a dced service. The actual data is maintained elsewhere. Each entry consists of the following structure members: id A unique identifer of type uuid_t that dced maintains for every data item it maintains name The name for the data item. The data type is dced_string_t . description A brief description the data item (of type dced_string_t) for the convenience of human users. storage_tag A string of type dced_string_t describing the location of the actual data. This is implementation- specific and may be a file (with a pathname) on the host system or a storage identifier for the dced process. dced_entry_list_t An entry list is a uniform way to list the data items a dced service maintains. The entry list structure contains a list of all the entries for a given service. For example, the complete list of all entries of hostdata, server configuration data, server execution data, and keytab data are each maintained in separate entry lists. The structure consists of the following: count An unsigned32 number representing the number of entries in the list. list An array of entries where each element is of type dced_entry_t. dced_key_t A key consists of the following structure members: principal A dced_string_t type string representing the principal for the key. version An unsigned32 number representing the version number of the key. authn_service An unsigned32 number representing the authentication service used. passwd A pointer to a password. This is of type sec_passwd_rec_t . See also the Security introduction reference page, sec_intro. dced_key_list_t A key list contains all the keys for a given key table and consists of the following structure elements: count An unsigned32 number representing the number of keys in the list. list An array of keys where each element is of type dced_key_t. dced_keytab_cursor_t The keytab cursor is an opaque pointer used to keep track of a location in a key list between calls that traverse the list. dced_opnum_list_t A list of operation numbers is used in the service_t structure. This structure consists of the following fields: count An unsigned32 number representing the number of operations in the list. list An array of UUIDs where each element is of type uuid_t. dced_service_type_t The dced service type distinguishes the services provided by dced. It is an enumerated type used mainly in a parameter of the dced_binding_from_rpc_binding() routine. It can have one of the following values: dced_e_service_type_hostdata The host data management service dced_e_service_type_srvrconf The server configuration management service dced_e_service_type_srvrexec The server execution management service dced_e_service_type_secval The security validation service dced_e_service_type_keytab The key table management service dced_e_service_type_null A NULL service type used internally dced_string_t This data type is a character string from the Portable Character Set (PCS). dced_string_list_t A list of strings with the following format: count An unsigned32 number representing the number of strings in the list. list An array of strings where each element is of type dced_string_t. dced_tower_list_t A list of protocol towers used in the service_t structure. This structure consists of the following fields: count An unsigned32 number representing the number of protocol towers in the list. list An array of pointers where each element is a pointer to a protocol tower of the type sec_attr_twr_set_p_t. This data type is described in the sec_intro reference page. server_fixedattr_t This structure is a field in the server_t structure. It contains the following fields: startupflags This field is of type unsigned32 and can be any combination of the following bits: server_c_startup_at_boot This means that dced should start the server when dced is started. server_c_startup_auto This means that the server can be started automatically if dced determines there is a need. server_c_startup_explicit This means dced can start the server if it receives an explicit command to do so via dced_server_start() or the dcecp operation server start. server_c_startup_on_failure This means that the server should be restarted by dced if it exits with an unsuccesful exit status. Several bits are also reserved for vendor-specific startup and include server_c_startup_vendor1, server_c_startup_vendor2, server_c_startup_vendor3, and server_c_startup_vendor4. flags This represents the execution state of the server and is the unsigned32 type. This field is maintained only by dced and should not be modified. Valid values to check for are self-explanatory and include the following: server_c_exec_notrunning server_c_exec_running Several bits are also reserved for vendor-specific execution states and include: server_c_exec_vendor1 server_c_exec_vendor2 server_c_exec_vendor3 server_c_exec_vendor4 program This is the full path name of the server and is of type dced_string_t. arguments This is a list of arguments for the server and is of type dced_string_list_t. prerequisites This is an advisory field that means this server is a client of other prerequisite servers whose IDs are in a list of type uuid_list_t. The UUIDs should be the id fields from the server_t structures of the relevent servers. keytables This is a list of keytab entry UUIDs representing the key tables for this server and is of type uuid_list_t. posix_uid This is a POSIX execution attribute for the user ID. It is of type unsigned32. posix_gid This is a POSIX execution attribute for the group ID. It is of type unsigned32. posix_dir This is a POSIX execution attribute for the directory in which the server started when it is invoked. It is of type dced_string_t. server_t The DCE Host daemon describes a server as follows: id Each server has a unique ID of type uuid_t. name Each server's name is of type dced_string_t. entryname The server's entry name is a hint as to where the server appears in the namespace. This is of type dced_string_t. services Each server offers a list of services specified in a list of type service_list_t. This structure has the following members: count An unsigned32 number representing the number of services in the list. list A pointer to an array of services where each element is of type service_t. fixed This is a set of attributes common to all DCE implementations. The data type is server_fixedattr_t. attributes This field is of type dced_attr_list_t and contains a list of attributes representing the behavior specific to a particular server or host. prin_names This field is a list of principal names for the server and is of type dced_string_list_t. exec_data Data about an executing server is maintained in a tagged union (named tagged_union) with a discriminator of type unsigned32 named execstate representing the server's execution state. The union has the following two execution states: server_c_exec_notrunning For the case where the server is not running, the union member has no value. For example: if(server->exec_data.execstate == server_c_exec_no) server->exec_data.tagged_union = NULL; server_c_exec_running For the case where the server is running, and the value of the union member is a srvrexec_data_t data type named running_data. A srvrexec_data_t structure contains the following members: instance Each instance of a server on a host is identified with a UUID (type uuid_t). posix_pid Each server has a POSIX process ID of type unsigned32. service_t This structure describes each service offered by a server. The server_t structure, described earlier, contains an array of these structures. The service_t structure contains the following fields: ifspec An interface specification of type rpc_if_id_t, generated by an idl compilation of the interface definition representing the service. This data type is described in the rpc_intro reference page. ifname An interface name of type dced_string_t. annotation An annotation about the purpose of the interface (type dced_string_t). This field is for user display purposes only. flags The flag field is of type unsigned32 and currently has only one bit field defined, service_c_disabled. If this flag is set, it indicates that the service is not currently available for the server. Also, the dced Endpoint Mapper will not map an endpoint to a disabled service. Several values are also reserved for vendor-specific use and include service_c_vendor1, service_c_vendor2, service_c_vendor3, and service_c_vendor4. entryname The entry name (type dced_string_t) is a hint as to where this service appears in the namespace. If the value is NULL, the value in the entryname field of the server_t structure is used. objects This is a list of objects supported by the service. The list is of type uuid_list_t. operations This is a list of operation numbers of type dced_opnum_list_t. This field is not currently used. towers This is a list of protocol towers of type dced_tower_list_t, specifying the endpoints where this server can be reached. srvrexec_stop_method_t The server execution stop method is an enumerated type with one of the following values: srvrexec_stop_rpc Stops the running server gracefully by letting the server complete all out- standing remote procedure calls. This causes dced to invoke the rpc_mgmt_server_stop_listening() routine in that server. srvrexec_stop_soft This uses a system-specific mechanism such as the SIGTERM signal. It stops the running server with a mechanism that the server can ignore or intercept in order to do application-specific cleanup. srvrexec_stop_hard This uses a system-specific mechanism such as the SIGKILL signal. It stops the running server immediately with a mechanism that the server cannot inter- cept. srvrexec_stop_error This uses a system-specific mechanism such as the SIGABRT signal. The local operating system captures the server's state before stopping it, and the server can also intercept it. uuid_list_t A list of UUIDs in the following format: count An unsigned32 number representing the number of UUIDs in the list. list A pointer to an array of UUIDs where each element is of type uuid_t. 2 DCE_TOOLS NAME dce_tools_intro - Introduction to the general DCE administration tools DESCRIPTION This section describes publicly accessible DCE administration commands that are general to DCE rather than specific to a particular component. These commands are as follows: csrc The csrc utility is the code set registry compiler, which builds a DCE character and code set registry on a host from a source file supplied by a cell administrator. Administrators run the csrc utility when they are building an "internationalized" DCE cell. dce_config The dce_config shell command invokes a menu-driven interface that installs, configures, and starts up DCE. The dce_config command displays a hierarchy of menus and invokes individual installation and configuration routines, according to users' menu selections. dcecp The dcecp control program is the primary DCE administration interface, providing remote access to routine DCE administrative functions. dced The DCE host daemon is a process that provides services for the local host, and is also the server used by remote applications to access these host services. getcellname Returns the name of the local cell. RELATED INFORMATION See each command's reference page for further information. 3 csrc NAME csrc - Builds a DCE character and code set registry on a host SYNOPSIS csrc [argument] ... ARGUMENTS -i source_filename Reads code set values from the source file you specify rather than from the default code set registry source file dce$common:[etc]code_set_registry.txt -m intermediate_cs_name Indicates the code set to be used as an intermediate code set -o destination_filename Places the generated code set registry file in the location you specify rather than in the default location dce$common:[etc]code_set_registry.db DESCRIPTION The Code Set Registry Compiler csrc creates a character and code set registry file from the information supplied in a character and code set registry source file. A code set registry source file is composed of a series of code set records. Each record describes, in human-readable form, the mapping between an OSF-registered or (optionally) a user-defined unique code set value and the character string that a given operating system uses when referring to that code set (called the "local code set name"). A code set registry file is the binary version of the source file; the DCE RPC routines for character and code set interoperability use the file to obtain a client's or a server's supported code sets and to translate between operating system-dependent names for code sets and the unique identifiers assigned to them. A code set registry file must exist on each host in an "internationalized" DCE cell (a DCE cell that supports applications that use the DCE RPC character and code set interoperability features). CREATING THE SOURCE FILE Code set registry source files are created for input to csrc in two instances: + By DCE licensees, when they are porting DCE to a specific operating system platform and plan for their DCE product to support internationalized DCE applications. In this instance, DCE licensees modify a template code set registry source file supplied on the DCE source tape to contain, for each code set that their platform supports, the local code set names for those supported code sets. Licensees can also add to this file any vendor-specific, non-OSF registered code set names and values that their platform supports. + By cell administrators, when they are configuring machines that are part of an internationalized DCE cell. In this instance, the cell administrator adds the local code set names of any additional code sets that the site supports to the licensee- generated code set registry source file for each different operating system platform that exists in the cell. The cell administrator can also add to each platform-specific source file any site-specific, non-OSF registered code set names and values. Each code set record specifies one code set, and has the following form: start field_list end where field_list consists of the following keyword-value or keyword- text pairs: description text A comment string that briefly describes the code set. The text field can contain multiple lines; use the backslash character (\) to continue the line. Use this field to give a detailed description of the code set and character set(s). loc_name text A maximum 32-byte string (31 character data bytes plus a terminating NULL) that contains the operating system- specific name of a code set or the keyword NONE. Use this field to specify the name that your site uses to refer to this code set and the code set converters associated with it. For example, on UNIX platforms, code set converters are usually implemented under the iconv scheme. Check the iconv converter directory to determine the code set names. rgy_value value A 32-bit hexadecimal value that uniquely identifies this code set. A registry value can be one that OSF has assigned or one that a DCE licensee or cell administrator has assigned. Licensee or cell administrator-defined values must be in the range 0xf5000000 through 0xfffffff. char_values value[:value] One or more 16-bit hexadecimal values that uniquely identify each character set that this code set encodes. A character value can be one that OSF has assigned or one that a DCE licensee or a cell administrator has assigned. Use the colon character (:) to separate multiple character set values. max_bytes value A 16-bit value that specifies the maximum number of bytes this code set uses to encode one character. The count should include any single-shift control characters, if used. In the source file, braces({}) can be used as synonyms for the start and end keywords. Use one or more spaces or tabs to separate field names and values. An unquoted # (number sign) introduces a comment; in this case, the csrc utility ignores everything between the comment character and the end of the line. The OSF DCE source tape provides a partial version of a code set registry source file in the file /usr/lib/nls/csr/code_set_registry.txt. This source file contains records for all OSF-registered code sets, and assigns the text string NONE to loc_name fields intended for modification to a local code set name. DCE licensees who port DCE to their operating system platform and who plan to support internationalized DCE RPC applications must replace the NONE text string with their local name for the code set, for each code set that their operating system platform supports. If their platform does not support a given code set, they must leave the NONE keyword in the code set record. Cell administrators of internationalized DCE cells carry out the same procedure on the licensee-supplied, platform-specific source files that exist at their site. For each platform-specific source file, they replace the NONE keyword with the local code set names for any site-specific supported code sets. DCE licensees and cell administrators can also add vendor-specific or site-specific code set values that have not been registered with OSF. These vendor or user-defined values must be in the range 0xf5000000 through 0xfffffff. Here is an excerpt from the OSF-supplied code set registry source file: start description ISO 8859:1987; Latin Alphabet No. 1 loc_name NONE rgy_value 0x00010001 char_values 0x0011 max_bytes 1 end start description ISO 8859-2:1987; Latin Alphabet No. 2 loc_name NONE code_value 0x00010002 char_values 0x0012 max_bytes 1 end start description ISO 8859-3:1988; Latin Alphabet No. 3 loc_name NONE code_value 0x00010003 char_values 0x0013 max_bytes 1 end start description ISO 8859-6:1987; Latin-Arabic Alphabet loc_name NONE code_value 0x00010006 char_values 0x0016 max_bytes 1 end [...] start description ISO/IEC 10646-1:1993; UCS-2 Level 1 loc_name NONE code_value 0x00010100 char_values 0x1000 max_bytes 2 end [...] start description JIS eucJP:1993; Japanese EUC loc_name NONE code_value 0x00030010 char_values 0x0011:0x0080:0x0081:0x0082 max_bytes 3 end GENERATING THE CODE SET REGISTRY FILE DCE licensees use csrc to create licensee-supplied code set registry files for their internationalized DCE product. Cell administrators of internationalized DCE cells use the csrc utility to create site-specific code set registry files for each host in the cell. The cell administrator runs the csrc program on each host in the cell. When invoked without options, csrc uses the default source file dce$common:[etc]code_set_registry.txt and creates the default output file dce$common:[etc]code_set_registry.db. Use the -i and -o options to redirect csrc to use a specific source file or generate a specific output file. The csrc utility also generates a log file named CSRC_LOG in the current directory. ADDING INTERMEDIATE CODE SETS Use the -m option to add a maximum of five intermediate code set names to the code set registry file's intermediate code set priority list. The order in which you specify intermediate code sets determines their order of precedence in the list; that is, the first intermediate code set you specify with -m becomes the first intermediate code set in the priority list, and thus will be the first code set used should an intermediate code set be required for client-server communication. If you do not specify intermediate code sets with -m, the Universal code set ISO 10646 will be used as the default intermediate code set. RESTRICTIONS You need write permission to the dce$common:[etc] directory, which usually requires privileges. FILES dce$common:[etc]code_set_registry.txt Default pathname for code set registry source file. dce$common:[etc]code_set_registry.db Default pathname for code set registry object file EXAMPLES % csrc -i dia0:[test.i18n_app]code_set_registry.txt - -o code_set_registry.db s In the previous example, the log file CSRC_LOG is created in the current working directory, testi18n_app. RELATED INFORMATION FUNCTIONS: dce_cf_get_csrgy_filename dce_cs_loc_to_rgy dce_cs_rgy_to_loc rpc_rgy_get_codesets BOOKS: OSF DCE Administration Guide OSF DCE Application Development Guide-Core Components 3 dce_config NAME The dce$setup.com command file replaces the dce_config command. See the dce$setup.com help for more information. 3 dcecp NAME dcecp - An administrative interface for performing DCE management tasks. The interface accepts interactive commands and scripts written with the dcecp language. SYNOPSIS dcecp dcecp script_name dcecp -c command ARGUMENTS script_name The script_name is the filename of a user-defined script containing dcecp commands. -c command The command is a valid dcecp command. For a description of the dcecp command format, see "Administration Objects," below. DESCRIPTION The dcecp control program is the primary DCE administration interface, providing remote access to routine DCE administrative functions from any DCE Version 1.1 platform. The dcecp control program is built on a portable command language called the Tool Command Language (Tcl). Tcl allows the use of variables, if statements, list processing functions, loop functions and many other features commonly found in command languages. The control program extends these features providing a set of commands for manipulating specific DCE objects. The control program also includes task scripts to help administrators perform some routine DCE management functions. Refer to the DCE Administration Guide Core Volume for information about the basic concepts and features of dcecp. All of TCL is included in the dcecp language. INVOKING AND TERMINATING DCECP The dcecp control program allows you to invoke dcecp commands in the following modes: + Interactive mode + Command line mode Interactive Mode Activate interactive mode by entering the dcecp command without any arguments . At the dcecp prompt enter a dcecp command. The dcecp program executes the command, displays the result, and is ready to accept another command. $ dcecp dcecp> directory list /.: -directories /.:/hosts /.:/subsys dcecp> Command Line Mode Activate command line mode from the system prompt using one of the following methods: + Enter the dcecp command with a filename of a script containing dcecp commands (and/or other valid Tcl commands) as follows: $ dcecp myown.Tcl + Enter the dcecp command with the -c option followed by a dcecp command. $ dcecp -c directory create /.:/admin/printers Enter multiple dcecp commands by separating them with a semicolon (;) and enclosing the commands in double quotes (""). Remember to enclose case sensitive characters double quotes. Multiple commands must be on a single line as follows: $ dcecp -c "directory create /.:/admin/printers;directory show" Terminate an interactive dcecp session using the exit and quit commands. Use the following command syntax: exit n quit Use the n argument to specify the exit value returned to DCL. If no value is specified, exit passes the return value of the most recent command to DCL. The following example terminates a session and returns an exit value of 56 to the DCL: dcecp> exit 56 By default, dcecp returns 1 on success and %X00038008 if a command fails. STARTUP SCRIPTS When you invoke dcecp the following script files are executed in the order shown: tcl$library:init.tcl contains the standard Tcl initialization scripts with definitions for the unknown command and the auto_load facility "$dcecp_library/init.dcecp" contains the initialization scripts implementing the dcecp commands and tasks. The implementation sets the Tcl variable dcecp_library to dceshared/dcecp by default. $HOME/.dcecprc contains user customizations. ADMINISTRATION OBJECTS A dcecp command has the following syntax: object operation [argument] [-option [value]] ... where: object Specifies the name of a dcecp administration object. Examples of administration objects are CDS directories, access control lists (ACLs), DTS servers, server control objects, and so on. Each administration object is briefly described below. operation Specifies the name of an action such as create, show, or remove, that is to be performed on an administration object. For complete descriptions of operations supported by each dcecp object, refer to individual object reference pages. Common operations are briefly described below. argument Specifies the name of one or more specific objects to operate on. Most, but not all, dcecp objects take an argument. Refer to the individual reference pages for descriptions of the arguments supported by various objects. -option Specifies a qualifier that controls the precise behavior of a dcecp command. Most, but not all, dcecp commands take options. Specify options by preceeding the option name with a hyphen as in -replica. Some options take an argument that can be a name or a value. The following example shows a -clearinghouse option and its argument which is the name of a CDS clearinghouse. directory create /.:/admin -clearinghouse /.:/boston_ch The dcecp program supports the following dcecp administration objects. For complete descriptions of the administration objects, refer to the individual object reference pages. account Manages an account in the DCE Security Service registry. acl Creates, modifies, and removes access control lists. attrlist Manipulates attribute lists. aud Manages the audit daemon (auditd) on a DCE host. audevents Manages audit event classification on a DCE host. audfilter Manages audit event filters on a DCE host. audtrail Controls the output format for audit events captured on a DCE host. cdsalias Manages cell names known to CDS. cdscache Manages the CDS clerk cache on a DCE host. cell Manages cell configuration information. cellalias Manages cell names across all of DCE. clearinghouse Manages CDS clearinghouse operations in a DCE cell. clock Manages the clock on a local DCE host. directory Manages directories in the DCE Cell Directory Service. dts Manages Distributed Time Service servers and clerks. endpoint Manages endpoint information in a DCE host's endpoint map. group Manages groups in the DCE Security Service registry. host Manages hosts within a cell. hostdata Manages a DCE host's principal name and cell affiliation information on the host. keytab Manages server passwords on DCE hosts. link Manages softlinks in the DCE Cell Directory Service. log Manages routing for DCE serviceability messages. name Manipulates names in the DCE namespace. object Manages object entries in the DCE Cell Directory Service. organization Manages organizations in the DCE Security Service regis- try. principal Manages principals in the DCE Security Service registry. registry Manages the database of a DCE Security Service registry. rpcentry Manages a server entry stored in the DCE Cell Directory Service. rpcgroup Manages a group entry stored in the DCE Cell Directory Service. rpcprofile Manages a profile entry stored in the DCE Cell Directory Service. schema Manages the schema information for extended registry attributes. secval Manages the security validation service in dced. server Manages servers and their configuration information on DCE hosts. user Manages a DCE user. utc Manipulates UTC timestamps. uuid Manipulates (generate or compare) UUID's. COMMON OPERATIONS This section gives a description of operations that are common to more than one object. Some operations presented here are implemented in all objects, some in only a few, and some only for specific types of objects such as containers (for instance, CDS directories). The descriptions in the sections on individual objects may override some of the information presented here. Usually this is only in the form of an operation accepting more options, but other changes are possible. add Adds an object to a container. It is implemented for all objects that represent containers. Returns an empty string on success. The argument is a list of names of containers. The required -member option is used to specify the name of the member to be added to the containers. It's value is a list of members to be added. If lists are specified for both the -member option and as the argument, then each member name is added to each container. For example it is used to add a member to an RPC group, and is used to add an element to an RPC profile. catalog Returns the names of all instances of an object. It usually takes no argument. In some cases, though, an argument specifying a scope, such as a cellname, is optional. For example, the principal catalog command returns a list of all principals in the registry. Only implemented by those objects for which this is possible. By default, fullnames are returned. Some objects will support a -simplename option which will return names in a shorter form (either relative or not fully qualified). The order of the returned list depends on the object. create Creates a new instance of an object. Takes one argument which a list of names of instances to be created. Returns an empty string on success. Returns an error if the object already exists. For some objects this command takes a -attribute option or a set of attribute options to create attributes on the new object. delete Destroys an instance of the object. Takes one argument which a list of names of instances to be deleted. Returns an empty string on success. If the object does not exist, an error is returned. help Returns help information on the object as described in the Help System section. Takes an argument which may be an operation supported by the object or the -verbose option to return more information. list Returns a list of the names of all the members of a container. This operation returns names of members, never any other (e.g., attribute) information about the members. It is implemented on all objects that represent containers. The argument is a list of names of containers to return the children of. The order of the returned list is dependent on the object. If more than one container name is given as an argument, all the member names are returned in one list. modify This operation is used to modify attributes, policies, counters, or any other information in an object. This fact means that all attributes, policies, counters, etc. in any one object must have unique names. It will not be available to all objects. Returns an empty string on success. The argument is a list of names of objects to modify. All objects are modified in the same way. The specific modification is described by the use of one or more of the -add, -remove, or -change options. If more than one is used, then the whole modify operation is treated atomically in that either it all will work, or none of it will. The order of the options does not matter. Each option may only be used once per command invocation. If more then one attribute is to be added, then the value of that option should be an attribute list. -add Used to add an attribute to an object or merely to add values to an existing attribute. The value of this option is an attribute list. -remove Used to remove an entire attribute or merely some values from an object. The value of this option is an attribute list. -change Used to change one attribute value to another. The value of this option is an attribute list. operations Returns a list of the operations supported by the object. It takes no arguments, and always returns a Tcl list suitable for use in a foreach statement. The order of the elements is alphabetical with the exception that help and operations are listed last. If the user wants them sorted they should use: lsort [object operations] remove Removes an object from a container. It is implemented for all objects that represent containers. The argument is a list of names of containers. The remove command requires one option, -member, which is used to specify the name of the member to be removed from the container. The value is a list of names of members of the containers. If the value of this option and the argument to the command are both lists, then each listed member is removed from each specified container. If the members do not exist an error is returned. rename This operation changes the name of a specified object. The argument is a single name of an object to be renamed, i.e., it cannot be a list. Takes a required -to option with a value of the new name. The value may not be a list. Returns an empty string on success. show Returns information about an object instance. Objects can have various types of information such as attributes, counters, policies, etc. The show command is used to return any of this information. Options are passed to the command to specify what information is to be returned. Most of the options used for this purpose are in the plural form such as -all, -attributes, -counters, and -members. Unlike the list command which returns information about the members of a container, the show command only looks at the named object instance. If it is a container, it does not return information about the members, only the container itself. This command takes one argument which is a list of names of instances to be shown. synchronize Tells the instance to synchronize with any replicas of itself. In CDS terminology this will perform a skulk on a directory, in DTS it will cause a server to synchronize. It is to be implemented for all objects that support replication. Returns an empty string on success. The argument is a list of instance names to synchronize. If more than one instance name is given then each instance synchronizes, there is no relationship such as synchronize with each other, as this doesn't make sense for many objects. MISCELLANEOUS COMMANDS The dcecp program includes a set of commands you can use for performing miscellaneous operations. dcecp_initInterp This command will initialize a base Tcl interpreter with all the dcecp commands. errtext Takes a DCE status code as an argument and returns the text of the associated message as found in the message catalogs. The argument can be in decimal, octal (leading 0), or hexadecimal (leading 0x) notation. expand Takes a DCE name as an argument and returns the canonical form of the name. login Creates a new login context to be used for the rest of the dcecp session. Sets convenience variables _c and _u to the cell name and principal name of the principal that issued the login command. Convenience variables are discussed in a separate section of this reference page. Login contexts are stacked. Takes an account name as an argument. The password is prompted for and not echoed to the screen. Also takes the -password option to enter a password. logout Logs you out of the current login context as established with a previous login command. Only contexts created with dcecp's login can be logged out of. Trying to logout of an inherited context results in an error. Leaving dcecp will do a logout for all contexts created in the session. quit Exits from dcecp. A synonym of the Tcl builtin command exit. resolve Takes a partial string binding and returns a fully bound string binding. Takes a require -interface option and an optional -object option with an interface identifier as an argument to provide enough information for the mapping to occur. shell Spawns a subprocess to execute an OpenVMS command for the user. When the command terminates, control is returned to dcecp. If called with arguments, they are passed to the subprocess and executed. Control is returned upon completion. Always returns an emptry string, though an error exception is generated if the subprocess exits abnormally. COMMAND PROCESSING The dcecp control program supports the Tcl built-in commands as well as its own commands. If a command name is unknown to dcecp, it is passed to the unknown command and dcecp evaluates it using the following algorithm: + If the command is found in a dcecp script file, dcecp executes the command + If the command exists as an executable OpenVMS program, dcecp executes the command. Therefore, you can invoke any OpenVMS command from the dcecp prompt (for example, DIRECTORY). Because you don't leave dcecp, you don't lose any context you have established. + If you have invoked the command at the top level of the dcecp shell and the command is a unique abbreviation for another command, dcecp invokes the command. ABBREVIATIONS dcecp makes use of two mechanisms to allow all object names, operation names, and options to be abbreviated to the shortest unique string in interactive commands. The first mechanism relies on the unknown command whose behavior is described previously in the Command Processing section of this reference page. The second mechanism used for abbreviations is built-in to the individual dcecp commands themselves. This allows the operation name to be abbreviated to the shortest unique operation supported for an object, and the options to be abbreviated to the shortest unique string representing an option supported by an object and operation. For example, consider the directory create operation: directory create /.:/admin/printers/ascii -replica -clearinghouse SFO_CH In the abbreviated form, the same operation can be entered as: dir cre /.:/admin/printers/ascii -r -c SFO_CH Although abbreviating commands is a good way to save typing in interactive commands, abbreviations are not recommended for use in scripts. New procedures in scripts can cause abbreviations to become ambiguous. Furthermore, abbreviations aren't always portable. When scripts move to other machines, some definitions may be left behind so scripts won't work correctly. Always spell out complete names in scripts. SYNTAX The dcecp commands have a default word order which is object operation. This order facilitates adding new objects because new objects can simply be added along with their operations. You can configure dcecp to accept commands ordered as operation object by loading a script called verb-object.dcecp. Users who have access to the operation object order continue to have access to the object operation order. You can load the script for all users on a host by including the following line in the system's init.dcecp file: source verb-object.dcecp You can configure operation object for individual users by including the line in that user's .dcecprc file. ATTRIBUTE LISTS Many of the commands need to specify attributes to operate upon. For example, the modify command allows attributes to be changed and the create command often allows attributes to be created along with the object. In all cases, you can use an attribute list to specify the attributes and their values. This makes passing information from one command to another very easy. For example, an ACL copy operation could be written as follows: # copy acl name1 to acl name2 # no error checking proc acl_copy {name1 name2} { acl replace $name2 -acl [acl show $name1] } ATTRIBUTE OPTIONS While attribute lists are useful for writing scripts, they are often not user-friendly. For those objects that have a fixed list of attributes (for instance, principal and dts, but not object), wherever an attribute list is allowed, options for each attribute that are named the same as the attribute are allowed followed by their values. For example, the following are equivalent: principal create melman -attribute {{quota 5} {uid 123}} principal create melman -quota 5 -uid 123 LISTS OF LISTS The dcecp control program intrepreter relies on list structures as a way to parse command input and return command output. For instance, the -remove option in the following example uses a list to group the attribute and value parts of the option argument together. The example is a command that removes some ACL's from an object called /.:/foo: acl modify /.:/foo -remove {user melman} The argument to the -remove option is an ACL Entry. The ACL Entry happens to be a list where the first element describes the ACL Type, in this case user, and the second is the key for which user, in this case melman. However, the -remove option may take a list of ACL Entries, so the following is valid as well: acl modify /.:/foo -remove {{user melman} {user salamone}} Lists of one value that do not contain spaces, do not need braces. The string syntax of an ACL Entry allows the type and key to be separated by a colon (:), so the following are valid: acl modify /.:/foo -remove user:melman acl modify /.:/foo -remove {user:melman user:salamone} If there is only one ACL Entry given, that is, the -remove option's value has only one element (and that element does not contain spaces), then braces are not needed to delimit the list. The following are all valid, but all are examples with unnecessary braces: acl modify /.:/foo -remove {{user melman}} acl modify /.:/foo -remove {{{user melman}}} acl modify /.:/foo -remove {user:melman} acl modify /.:/foo -remove {{user:melman} {user:salamone}} CONVENIENCE VARIABLES All dcecp commands will set several variables on execution. The variables will contain the name of the object operated on, the return value of the last command, the cell name of the last object operated on, and so on. You can substitute the value of these variables into the next command to save typing. Convenience variables behave just like other variables in dcecp. Thus you can trigger variable substitution by prepending a dollar sign ($) before the name of the variable. Alternatively, you can trigger substitution using the set. The dcecp program ensures that the convenience variables are set only by the program; it prevents users from changing these variables. The dcecp program defines the following variables: _b Holds the name of the server bound to for the last command. This is actually a Tcl array where the indexes are used to identify the service. Currently there is only one defined index: sec. The value specifies the name of a server in whatever manner the service finds useful. This could be the name of an RPC server entry in the namespace, or a string binding, or the name of a cell. This variable may not be set by the user. _c Holds the cellname of the current principal. The login commmand sets the cell name (_c) and principal name (_u) convenience variables at login (see the login command). Users can set this variable to change the current login context. command. _n Holds a list of the names entered to the last command. These names are the names that the command operated on, typically entered as the third argument. Examples follow: dcecp> dir list /.: -simplename hosts subsys absolut_ch cell-profile fs lan-profile sec \ sec-v1 dcecp> echo $_n /.: dcecp> dir create {/.:/x /.:/y} dcecp> echo $_n /.:/x /.:/y _o Holds the object used in the last operation. For example, if the last command was dir show /.:, then _o is directory. _p Holds the parent of _n. If _n is a list, then this is a list of the same length, where each element is the parent of the corresponding element in _n. _r Holds the return value of the last executed command. _s Holds the name of the server bound to for the last command. This is actually a Tcl array where the indexes are used to identify the service. The currently defined indexes are: sec, cds, dts, and aud. The value specifies the name of a server in whatever manner the service finds useful. This could be the name of an RPC server entry in the namespace, or a string binding, or the name of a cell. Users can set this variable by issuing the set command. This lets users select which server is used. The values of this variable (array) are treated differently by each service. For example, the security service uses this variable to display the registry bound to for the last command, and is used as a default for the next registry operation. If bound to a read-only replica and an update is requested, dcecp will try to bind to the master registry to perform the change. The CDS service only attempts to communicate with the CDS server named by the variable. If the named CDS server cannot satisfy a request for any reason, the request fails. The auditing service and DTS uses its variable in a similar manner to the CDS server. To contact an audit daemon or DTS server on another host, set this variable to identify that server. For information about an object's use of this variable, see the object's reference page or use the object's help -verbose operation. _u Holds the current principal name. The login commmand sets the cell name (_c) and principal name (_u) convenience variables at login (see the login command). Users can set this variable to change the current login context. command. ERROR HANDLING All commands in dcecp return either a list of some information or an empty string on success. If an error occurs, dcecp returns an error message. The dcecp program also provides a catch command to help scripts catch errors and invoke error handlers. The dcecp program provides two global variables that store error information returned from commands. The errorInfo variable contains the stacktrace of the error messages. When errors occur dcecp commands return one line error messages by default. If the variable dcecp_verbose_errors is set to 1, then a stack trace as it would appear in errorInfo is output as well. When a dcecp command argument is a list of objects, the command operates on multiple objects. These operations are usually performed iteratively. If an error occurs, the command aborts at the time of error producing an exception. Some operations will have finished and others will not have. The operations are always performed in the order listed, and the error message should make it clear on which object the command failed. HELP The dcecp program provides several kinds of help. All return help strings obtained from appropriate message catalogs. To see which operations an object supports, enter an object operations command. All dcecp objects support the operations command. An example is: dcecp> principal operations catalog create delete modify rename show help operations dcecp> This provides simple help similar to usage messages found on many systems. Users unsure of an operation name or if an operation is supported by an object can use this command to find the answer. The output is a dcecp list that could be used by other dcecp commands. To see other information about an object, use an object's help command. All dcecp objects have a help command which offers three kinds of information. + View brief information about an object's operations using help without arguments or options. Operations are listed in alphabetical order, with the operations and help commands listed last because all objects support these commands. An example is: dcecp> principal help catalog Returns all the names of principals in the registry. create Creates a DCE principal. delete Deletes a principal from the registry. modify Changes the information about a principal. rename Renames the specified principal. show Returns the attributes of a principal. help Prints a summary of command-line options. operations Returns a list of the valid operations for this command. dcecp> + View brief information about options supported by an operation using help with one argument-the name of the operation. This command returns attribute options in alphabetic order followed by other options also in alphabetic order as well. If no options are supported, an empty string is returned. An example is: dcecp> principal help create -alias Indicates the principal name is an alias of the uid. -attribute Specify principal attributes in an attribute list format. -fullname Fullname of the principal. -quota How many registry objects can the principal create. -uid User Identifier of the new principal. -uuid Orphaned UUID to be adopted by the principal. dcecp> + View a short description of a dcecp object using the help command with the -verbose option. This command returns text explaining what the object represents and how to use it. An example is: dcecp> principal help -verbose This object allows manipulation of principal information stored in the DCE registry. The argument is a list of either relative or fully-qualified principal names. Specify fixed attributes using attribute options or an attribute list. Specify any extended attributes using an attribute list. Principal operations connect to a registry that can service the request. Specify a particular registry by setting the _s(sec) convenience variable to be a cell-relative or global replica name, or the binding of the host where the replica exists. The completed operation sets _b(sec) convenience variable to the name of the registry contacted. dcecp> COMMAND LINE EDITING You can edit a line before it is sent to dcecp by using standard OpenVMS command line editing. COMMAND HISTORY AND COMMAND LINE RECALL The dcecp program includes a history facility that stores previously entered commands. View the stored commands using the history command. By default, the history facility stores the 20 most recent commands but you can use a history keep command to change this as in: dcecp> history keep 50 dcecp> Each stored command is numbered so you can recall it using an exclamation point (!) followed by the event number. dcecp> !7 WHATEVER EVENT 7 WAS... dcecp> Recall a specific command using an exclamation point (!) followed by the first unique characters of a previously entered command dcecp> !dir WHATEVER EVENT dir WAS... dcecp> You can also recall and revise the most recent command using the uparrow and command line editing familiar to OpenVMS users. dcecp> directory vreate /.:/admin/printers dcecp> ^vreate dcecp> create [ COMMAND OUTPUT ] EXAMPLES INVOCATIONS The following examples show some ways to issue dcecp commands. + Invoke dcecp for interactive use. $ dcecp dcecp> + Invoke dcecp for a single command. $ dcecp -c clock show 1994-04-21-19:12:42.203+00:00I----- $ + Invoke dcecp and run a script. $ dcecp get_users.Tcl $ SIMPLE OBJECT COMMANDS dcecp> acl show -ic /.: {unauthenticated r--t---} {group subsys/dce/cds-admin rwdtcia} {group subsys/dce/cds-server rwdtcia} {any_other r--t---} dcecp> $ dcecp -c directory show /.:/subsys {RPC_ClassVersion 0100} {CDS_CTS 1994-04-14-19:26:22.539+00:00I0.000/00-00-c0-8a-df-56} {CDS_UTS 1994-04-18-16:39:58.199+00:00I0.000/00-00-c0-8a-df-56} {CDS_ObjectUUID 00524676-98de-1dad-9263-0000c08adf56} {CDS_Replicas {Clearinghouse_Uuid 000ad28c-98c2-1dad-9263-0000c08adf56} {Clearinghouse_Name /.../brain_cell.osf.org/pmin17_ch} {Replica_Type Master} {Tower ncacn_ip_tcp:130.105.1.227[]} {Tower ncadg_ip_udp:130.105.1.227[]}} {CDS_AllUpTo 1994-04-18-22:40:35.326+00:00I0.000/00-00-c0-8a-df-56} {CDS_Convergence medium} {CDS_ParentPointer {Parent_UUID 00972ee5-98c4-1dad-9263-0000c08adf56} {Timeout {expiration 1994-04-19-16:39:58.049} {extension +1-00:00:00.000I0.000}} {myname /.../brain_cell.osf.org/subsys}} {CDS_DirectoryVersion 3.0} {CDS_ReplicaState on} {CDS_ReplicaType Master} {CDS_LastSkulk 1994-04-18-22:40:35.326+00:00I0.000/00-00-c0-8a-df-56} {CDS_LastUpdate 1994-04-18-16:39:58.199+00:00I0.000/00-00-c0-8a-df-56} {CDS_RingPointer 000ad28c-98c2-1dad-9263-0000c08adf56} {CDS_Epoch 0059e778-98df-1dad-9263-0000c08adf56} {CDS_ReplicaVersion 3.0} $ THE FOREACH LOOP dcecp> foreach i [group list temps] { > account modify $i temps research -expdate 6/30/95 } ABBREVIATIONS dcecp> clearin sh /.../brain_cell.osf.org/pmin17_ch {CDS_CTS 1994-04-14-19:25:54.051+00:00I0.000/00-00-c0-8a-df-56} {CDS_UTS 1994-04-14-19:31:46.020+00:00I0.000/00-00-c0-8a-df-56} {CDS_ObjectUUID 000ad28c-98c2-1dad-9263-0000c08adf56} {CDS_AllUpTo 1994-04-18-19:40:15.501+00:00I0.000/00-00-c0-8a-df-56} {CDS_DirectoryVersion 3.0} {CDS_CHName /.../brain_cell.osf.org/pmin17_ch} {CDS_CHLastAddress {Tower ncacn_ip_tcp:130.105.1.227[]}} {CDS_CHLastAddress {Tower ncadg_ip_udp:130.105.1.227[]}} {CDS_CHState on} {CDS_CHDirectories {dir_uuid 00972ee5-98c4-1dad-9263-0000c08adf56} {directory /.../brain_cell.osf.org}} {CDS_CHDirectories {dir_uuid 00524676-98de-1dad-9263-0000c08adf56} {directory /.../brain_cell.osf.org/subsys}} {CDS_CHDirectories {dir_uuid 0013b6b8-98e0-1dad-9263-0000c08adf56} {directory /.../brain_cell.osf.org/subsys/HP}} {CDS_CHDirectories {dir_uuid 00216e3e-98e1-1dad-9263-0000c08adf56} {directory /.../brain_cell.osf.org/subsys/HP/sample-apps}} {CDS_CHDirectories {dir_uuid 002a91da-98e2-1dad-9263-0000c08adf56} {directory /.../brain_cell.osf.org/subsys/dce}} {CDS_CHDirectories {dir_uuid 008f45f8-98e3-1dad-9263-0000c08adf56} {directory /.../brain_cell.osf.org/subsys/dce/sec}} {CDS_CHDirectories {dir_uuid 008dbc60-98e4-1dad-9263-0000c08adf56} {directory /.../brain_cell.osf.org/subsys/dce/dfs}} {CDS_CHDirectories {dir_uuid 00986692-98e5-1dad-9263-0000c08adf56} {directory /.../brain_cell.osf.org/hosts}} {CDS_CHDirectories {dir_uuid 00152a98-98e7-1dad-9263-0000c08adf56} {directory /.../brain_cell.osf.org/hosts/pmin17}} {CDS_ReplicaVersion 3.0} {CDS_NSCellname /.../brain_cell.osf.org} dcecp> 3 dced NAME dced - DCE Host daemon SYNOPSIS dced [-ifh] [-w route] [-b|-p|-s] [-e|prot_seq...] OPTIONS -h Prints the dced usage and exits. -i Initializes the dced databases and ACLs and exits. If the databases exist, this option displays an error. See the list of databases in the FILES section. -b Starts dced in bootstrap mode with the endpoint mapper service and ACLs. This mode means it may need to wait for other daemons such as secd and cdsd before it can perform its own initialization. -c Starts dced so it does not require DCE privacy encryption for remote key table management. The default is to use DCE privacy encryption. -e Starts dced without the endpoint mapper service. No protocol sequences are valid for this option. -f Starts the dced process in the foreground. The default is for dced to run in the background. -p Purges the existing machine context and removes the bindings file before starting. -s Starts dced without the security validation service. -w Sets the routing for serviceability. ARGUMENTS Establishes the serviceability routing for dced's messages. Starts dced by using the specified RPC protocol sequence string or strings. Possible values include ncadg_ip_udp (for a datagram protocol) and ncacn_ip_tcp (for a connection-based protocol). A complete list of the protocol sequences recognized can be found in dce/ep.idl. DESCRIPTION The DCE Host daemon is a process that provides services for the local host, and is also the server used by remote applications to access these host services. The DCE Host daemon services include the following: Endpoint Mapper The endpoint mapper service maintains a database called the local endpoint map which allows DCE clients to find servers, individual services provided by servers, and objects managed by services on the host. The endpoint mapper service maps interfaces, object UUIDs, and protocol sequence registrations to server ports (endpoints). Servers register their bindings with the local endpoint mapper, and the end- point mapper service on each host uses the local endpoint map to locate a compatible server for clients that do not already know the endpoint of a compatible server. Host Data Management The host data management service maintains local files of host data that include (among others) the host_name, cell_name, cell_aliases, and a post_processors file. The post_processors file contains program names matched with the other host data items (UUIDs). The dced runs the program if the corresponding host data item is changed. There may also be host-specific data files. Server Management The server management service maintains data that describes the startup configuration (srvrconf) and execution state (srvrexec) for each server. It also has the functionality to start or stop particular servers, and enable or disable specific services of servers. Security Validation The security validation service acts as the client side of the security server by assuring applications that the DCE Security daemon (secd) that the host is using is legitimate. In addition, this service logs into the local machine when dced is invoked and automatically updates the local machine principal's keys. Key Table Management The key table management service allows for remote maintenance of server's key tables (keytab files). The DCE Host daemon must be running before any other DCE-based servers are started. Each DCE host must run only a single dced, and it must run with privileges since it typically listens on privileged or reserved network ports. Typically, dced starts each time a host boots. (A file called SYS$MANAGER:DCE$RPC_STARTUP.COM is responsible for configuration issues such as deleting the endpoint map database and starting dced.) By default, the DCE Host daemon listens on one well-known port for each RPC protocol sequence (that is, each combination of an RPC protocol and a transport protocol) supported by the host on which it is running. A prot_seq argument lets you limit the protocol sequences on which dced listens. FILES dce$local:[var.dced]Ep.db dce$local:[var.dced]cell_aliases dce$local:[var.dced]Hostdata.db dce$local:[var.dced]cell_name dce$local:[var.dced]Srvrconf.db dce$local:[var.dced]host_name dce$local:[var.dced]Srvrexec.db dce$local:[var.dced]Acl.db dce$local:[var.dced]Keytab.db dce$local:[krb5]v5srvtab dce$local:[var.dced]Xattrschema.db dce$local:[000000]dce_cf.db dce$local:[var.dced]post_processors RELATED INFORMATION COMMANDS: hostdata, endpoint, server, secval, keytab, attribute LIBRARY CALLS: dce_server*, dced_*, rpc_mgmt_ep* BOOKS: OSF DCE Application Development Guide. 3 getcellname NAME getcellname - Gets the primary name of the cell SYNOPSIS getcellname DESCRIPTION The getcellname command prints the primary name of the local cell to standard output. If the command fails, it prints an error message to standard error. FILES dce$local[000000]dce_cf.db The local DCE configuration database. RELATED INFORMATION FUNCTIONS: dce_cf_get_cell_name 2 DCE_THREADS DESCRIPTION DECthreads, HP's multithreading run-time library, provides a set of interfaces for building multithreaded programs. One of these interfaces provides routines (with the prefix pthread_) that implement the IEEE Std 1003.1c-1995, POSIX System Application Program Interface, also known as POSIX Standard 1003.1c or POSIX.1c. Note that POSIX Standard 1003.1c now supersedes the POSIX draft standard 1003.4a. A thread is a single, sequential flow of control within a program. Within a single thread, there is a single point of execution. Most traditional programs consist of a single thread. Using DECthreads, a programmer can create more than one threads within a program. Threads execute concurrently, and, within a multithreaded pro- gram, there are at any time multiple points of execution. The threads in a given process execute within (and share) a single address space. There- fore, threads read and write the same memory locations. Synchronization elements such as mutexes and condition variables ensure that the shared memory is accessed correctly. DECthreads provides routines that allow you to create and use these synchronization elements. Mutexes and condition variables are discussed in the Guide to DECthreads. Users of previous versions of DECthreads should be aware that applications consistent with the P1003.4a/D4 interface require significant modifications to be upgraded to the DECthreads pthread (POSIX.1c) interface. See the discussion in the Guide to DECthreads. Routine names ending with the _np suffix denote that the routine is "not portable." That is, such a routine might not be available in other vendor implementations of POSIX 1003.1c. Each C module that utilizes DECthreads exceptions must include the pthread_exception.h header file. The Guide to DECthreads describes the use of DECthreads exceptions. The Guide to DECthreads describes important considerations for threaded application development, particularly for the OpenVMS operating system. Threads are packaged with the operating system. 3 Thread_Intro NAME intro - Introduction to DCE Threads DESCRIPTION DCE Threads are a set of routines that you can call to create a multi- threaded program. Multithreading is used to improve the performance of a program. Routines implemented by DCE Threads that are not speci- fied by Draft 4 of the POSIX 1003.4a standard are indicated by an _np suffix on the name. These routines are not portable. The pthread interface routines are grouped in the following functional categories: + General threads routines + Thread attributes object routines + Thread cancelation routines + Thread priority, concurrency, and scheduling routines + Thread-specific data routines + Mutex routines + Mutex attributes object routines + Condition variable routines + Condition variable attribute object routines DECthreads also provides routines that implement nonportable extensions to the POSIX 1003.1c standard. These routines are grouped into these functional categories: + Thread execution routines + Thread attributes routines + DECthreads global mutex routines + Mutex attributes routines + Condition variable routines + DECthreads exception object routines 4 General_Threads_Routines pthread_create Creates a thread object and thread. pthread_detach Marks a thread object for deletion. pthread_equal Compares one thread identifier to another thread identifier. pthread_exit Terminates the calling thread. pthread_join Causes the calling thread to wait for the termination of a specified thread and detach it. pthread_once Calls an initialization routine to be executed only once. pthread_self Obtains the identifier of the current thread. 4 Thread_Attributes_Object_Routines pthread_attr_destroy Destroys a thread attributes object. pthread_attr_getdetachstate Obtains the detachstate attribute from the specified thread attributes object. pthread_attr_getguardsize Obtains the guardsize attribute of the specified thread attributes object. pthread_attr_getinheritsched Obtains the inherit scheduling attribute from the specified thread attributes object. pthread_attr_getschedparam Obtains the scheduling parameters for an attribute of the specified thread attributes object. pthread_attr_getschedpolicy Obtains the scheduling policy attribute of the specified thread attributes object. pthread_attr_getscope Obtains the contention-scope attribute of the specified thread attributes object. pthread_attr_getstackaddr Obtains the stackaddr attribute of the specified thread attributes object. pthread_attr_getstacksize Obtains the stacksize attribute of the specified thread attributes object. pthread_attr_init Initializes a thread attributes object. pthread_attr_setdetachstate Changes the detachstate attribute in the specified thread attributes object. pthread_attr_setguardsize Changes the guardsize attribute of the specified thread attributes object. pthread_attr_setinheritsched Changes the inherit scheduling attribute of the specified thread attributes object. pthread_attr_setschedparam Changes the values of the parameters associated with the scheduling policy attribute of the specified thread attri- butes object. pthread_attr_setschedpolicy Changes the scheduling policy attribute of the specified thread attributes object. pthread_attr_setstackaddr Changes the stackaddr attribute in the specified thread attributes object. pthread_attr_setstacksize Changes the stacksize attribute in the specified thread attributes object. 4 Thread_Cancellation_Routines pthread_cancel Allows a thread to request that it, or another thread, terminate execution. pthread_cleanup_pop Removes a cleanup handler routine from the top of the cleanup stack and optionally executes it. pthread_cleanup_push Establishes a cleanup handler routine to be executed when the thread exits or is canceled. pthread_setcancelstate Sets the current thread's cancelability state. pthread_setcanceltype Sets the current thread's cancelability type. pthread_testcancel Requests delivery of any pending cancelation request to the current thread. 4 Thread_Priority_Concurrency_and_Scheduling_Routines pthread_getconcurrency Obtains the current concurrency level parameter for the process. pthread_getschedparam Obtains the current scheduling policy and scheduling parameters of a thread. pthread_getsequence_np Obtains a thread sequence number. pthread_setconcurrency Changes the current concurrency level parameter for the process. pthread_setschedparam Changes the current scheduling policy and scheduling parameters of a thread. 4 Thread_Specific_Data_Routines pthread_getspecific Obtains the thread-specific data associated with the specified key. pthread_key_create Generates a unique thread-specific data key. pthread_setspecific Sets the thread-specific data value associated with the specified key for the current thread. pthread_key_delete Deletes a thread-specific data key. 4 Mutex_Routines pthread_mutex_destroy Destroys a mutex. pthread_mutex_init Initializes a mutex with attributes specified by the attributes argument. pthread_mutex_lock Locks an unlocked mutex; if locked, the caller waits for the mutex to become available. pthread_mutex_trylock Attempts to lock a mutex; returns immediately if mutex is already locked. pthread_mutex_unlock Unlocks a locked mutex. 4 Mutex_Attributes_Object_Routines pthread_mutexattr_init Initializes a mutex attributes object. pthread_mutexattr_destroy Destroys a mutex attributes object. pthread_mutexattr_gettype Obtains the mutex type attribute of a mutex attributes object. pthread_mutexattr_settype Changes the mutex type attribute of a mutex attributes object. 4 Condition_Variable_Routines pthread_cond_broadcast Wakes all threads waiting on a condition variable. pthread_cond_destroy Destroys a condition variable. pthread_cond_init Initializes a condition variable. pthread_cond_signal Wakes at least one thread that is waiting on a condition variable. pthread_cond_timedwait Causes a thread to wait for a specified period of time for a condition variable to be signaled or broadcasted. pthread_cond_wait Causes a thread to wait for a condition variable to be signaled or broadcasted. 4 Condition_Variable_Attributes_Object_Routines pthread_condattr_destroy Destroys a condition variable attributes object. pthread_condattr_init Initializes a condition variable attributes object. 4 Non_Portable_Extensions DECthreads also provides routines that implement nonportable extensions to the POSIX 1003.1c standard. These routines are grouped into these functional categories: 5 Thread_Execution_Routines pthread_delay_np Causes a thread to delay execution. pthread_get_expiration_np Obtains a value representing a desired expiration time. pthread_getsequence_np Obtains the thread sequence number. 5 Thread_Attributes_Routines pthread_attr_getguardsize_np Obtains the guardsize attribute of the specified thread attributes object. pthread_attr_setguardsize_np Changes the guardsize attribute of the specified thread attributes object. 5 DECthreads_Global_Mutex_Routines pthread_lock_global_np Locks the DECthreads global mutex if it is unlocked. pthread_unlock_global_np Unlocks the DECthreads lobal mutex if it is locked. 5 Mutex_Attributes_Routines pthread_mutexattr_gettype_np Obtains the mutex type attribute of a mutex attributes object. pthread_mutexattr_settype_np Changes the mutex type attribute of a mutex attributes object. 5 Condition_Variable_Routines pthread_cond_signal_int_np Wakes one thread that is waiting on a condition variable (called from interrupt level only). 5 DECthreads_Exception_Object_Routines pthread_exc_get_status_np Obtains a system-defined error status from a DECthreads status exception object. pthread_exc_matches_np Determines whether two DECthreads exception objects are identical. pthread_exc_report_np Produces a message that reports what a specified DECthreads status exception object represents. pthread_exc_set_status_np Imports a system-defined error status into a DECthreads address exception object. 3 Application_Routines 4 exceptions NAME exceptions - Exception handling in DCE Threads DESCRIPTION DCE Threads provides the following two ways to obtain information about the status of a threads routine: o The routine returns a status value to the thread. o The routine raises an exception. Before you write a multithreaded program, you must choose only one of the preceding two methods of receiving status. These two methods cannot be used together in the same code module. The POSIX P1003.4a (pthreads) draft standard specifies that errors be reported to the thread by setting the external variable errno to an error code and returning a function value of -1. The threads reference pages document this status value-returning interface. However, an alternative to status values is provided by DCE Threads in the exception-returning interface. Access to exceptions from the C language is defined by the macros in the exc_handling.h file. The exc_handling.h header file is included automat- ically when you include pthread_exc.h. To use the exception-returning interface, replace #include with the following include statement: #include The following example shows the syntax for handling exceptions: TRY try_block [CATCH (exception_name) handler_block]... [CATCH_ALL handler_block] ENDTRY 4 pthread_attr_create NAME pthread_attr_create - Creates a thread attributes object SYNOPSIS #include int pthread_attr_create (pthread_attr_t *attr); PARAMETERS attr Thread attributes object created. DESCRIPTION The pthread_attr_create() routine creates a thread attributes object that is used to specify the attributes of threads when they are created. The attributes object created by this routine is only used in calls to pthread_create(). The individual attributes (internal fields) of the attributes object are set to default values. (The default values of each attribute are dis- cussed in the descriptions of the following services.) Use the following routines to change the individual attributes: o pthread_attr_setinheritsched() o pthread_attr_setprio() o pthread_attr_setsched() o pthread_attr_setstacksize() When an attributes object is used to create a thread, the values of the individual attributes determine the characteristics of the new object. Attributes objects perform in a manner similar to additional parameters. Changing individual attributes does not affect any threads that were previously created using the attributes object. RETURN VALUES If the function fails, -1 is returned and errno may be set to one of the following values: Return Error Description ___________________________________________________________ 0 Successful completion. -1 [ENOMEM] Insufficient memory exists to create the thread attributes object. -1 [EINVAL] The value specified by attr is invalid. RELATED INFORMATION FUNCTIONS: pthread_attr_delete pthread_attr_setinheritsched pthread_attr_setprio pthread_attr_setsched pthread_attr_setstacksize pthread_create 4 pthread_attr_delete NAME pthread_attr_delete - Deletes a thread attributes object SYNOPSIS #include int pthread_attr_delete(pthread_attr_t *attr); PARAMETERS attr Thread attributes object deleted. DESCRIPTION The pthread_attr_delete() routine deletes a thread attributes object and gives permission to reclaim storage for the thread attributes object. Threads that were created using this thread attributes object are not affected by the deletion of the thread attributes object. The results of calling this routine are unpredictable if the value specified by the attr parameter refers to a thread attributes object that does not exist. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description ___________________________________________________________ 0 Successful completion. -1 [EINVAL] The value specified by attr is invalid. RELATED INFORMATION FUNCTIONS: pthread_attr_create 4 pthread_attr_getinheritsched NAME pthread_attr_getinheritsched - Obtains the inherit scheduling attribute SYNOPSIS #include int pthread_attr_getinheritsched(pthread_attr_t attr); PARAMETERS attr Thread attributes object whose inherit scheduling attribute is obtained. DESCRIPTION The pthread_attr_getinheritsched() routine obtains the value of the inherit scheduling attribute in the specified thread attributes object. The inherit scheduling attribute specifies whether threads created using the attributes object inherit the scheduling attributes of the creating thread, or use the scheduling attributes stored in the attributes object that is passed to pthread_create(). The default value of the inherit scheduling attribute is PTHREAD_INHERIT_SCHED. RETURN VALUES On successful completion, this routine returns the inherit scheduling attribute value. If the function fails, errno may be set to one of the following values: Return Error Description ________________________________________________________________ Inherit scheduling Successful completion. attribute -1 [EINVAL] The value specified by attr is invalid. RELATED INFORMATION FUNCTIONS: pthread_attr_create pthread_attr_setinheritsched pthread_create 4 pthread_attr_getprio NAME pthread_attr_getprio - Obtains the scheduling priority attribute SYNOPSIS #include int pthread_attr_getprio(pthread_attr_t attr); PARAMETERS attr Thread attributes object whose priority attribute is obtained. DESCRIPTION The pthread_attr_getprio() routine obtains the value of the scheduling priority of threads created using the thread attributes object specified by the attr parameter. RETURN VALUES On successful completion, this routine returns the scheduling priority attribute value. If the function fails, errno may be set to one of the following values: Return Error Description _________________________________________________________ Scheduling priority Successful completion. attribute -1 [EINVAL] The value specified by attr is invalid. RELATED INFORMATION FUNCTIONS: pthread_attr_create pthread_attr_setprio pthread_create 4 pthread_attr_getsched NAME pthread_attr_getsched - Obtains the value of the scheduling policy attribute SYNOPSIS #include int pthread_attr_getsched(pthread_attr_t attr); PARAMETERS attr Thread attributes object whose scheduling policy attribute is obtained. DESCRIPTION The pthread_attr_getsched() routine obtains the scheduling policy of threads created using the thread attributes object specified by the attr parameter. The default value of the scheduling attribute is SCHED_OTHER. RETURN VALUES On successful completion, this routine returns the value of the scheduling policy attribute. If the function fails, errno may be set to one of the following values: Return Error Description ________________________________________________________________ Scheduling policy Successful completion. attribute -1 [EINVAL] The value specified by attr is invalid. RELATED INFORMATION FUNCTIONS: pthread_attr_create pthread_attr_setsched pthread_create 4 pthread_attr_getstacksize NAME pthread_attr_getstacksize - Obtains the value of the stacksize attribute SYNOPSIS #include long pthread_attr_getstacksize(pthread_attr_t attr); PARAMETERS attr Thread attributes object whose stacksize attribute is obtained. DESCRIPTION The pthread_attr_getstacksize() routine obtains the minimum size (in bytes) of the stack for a thread created using the thread attributes object specified by the attr parameter. RETURN VALUES On successful completion, this routine returns the stacksize attribute value. If the function fails, errno may be set to one of the following values: Return Error Description __________________________________________________________ Stacksize attribute Successful completion. -1 [EINVAL] The value specified by attr is invalid. RELATED INFORMATION FUNCTIONS: pthread_attr_create pthread_attr_setstacksize pthread_create 4 pthread_attr_setinheritsched NAME pthread_attr_setinheritsched - Changes the inherit scheduling attribute SYNOPSIS #include int pthread_attr_setinheritsched( pthread_attr_t attr, int inherit ); PARAMETERS attr Thread attributes object to be modified. inherit New value for the inherit scheduling attribute. Valid values are as follows: PTHREAD_INHERIT_SCHED This is the default value. The created thread inherits the current priority and scheduling policy of the thread calling pthread_create(). PTHREAD_DEFAULT_SCHED The created thread starts execution with the priority and scheduling policy stored in the thread attributes object. DESCRIPTION The pthread_attr_setinheritsched() routine changes the inherit schedul- -ing attribute of thread creation. The inherit scheduling attribute spe cifies whether threads created using the specified thread attributes obj ect inherit the scheduling attributes of the creating thread, or use the scheduling attributes stored in the thread attributes object that is passed to pthread_create(). The first thread in an application that is not created by an explicit call to pthread_create() has a scheduling policy of SCHED_OTHER. (See the pthread_attr_setprio() and pthread_attr_setsched() routines for more information on valid priority values and valid scheduling policy values, respectively.) Inheriting scheduling attributes (instead of using the scheduling attri- butes stored in the attributes object) is useful when a thread is creat- ing several helper threads-threads that are intended to work closely with the creating thread to cooperatively solve the same problem. For example, inherited scheduling attributes ensure that helper threads created in a sort routine execute with the same priority as the calling thread. RETURN VALUES If the function fails, -1 is returned, and errno may be set to one of the following values: Return Error Description ___________________________________________________________ 0 Successful completion. -1 [EINVAL] The value specified by attr is invalid. -1 [EINVAL] The value specified by inherit is invalid. RELATED INFORMATION FUNCTIONS: pthread_attr_create pthread_attr_getinheritsched pthread_attr_setprio pthread_attr_setsched pthread_create 4 pthread_attr_setprio NAME pthread_attr_setprio - Changes the scheduling priority attribute of thread creation SYNOPSIS #include int pthread_attr_setprio( pthread_attr_t *attr, int priority ); PARAMETERS attr Thread attributes object modified. priority New value for the priority attribute. The priority attribute depends on scheduling policy. Valid values fall within one of the following ranges: o PRI_OTHER_MIN <= priority <= PRI_OTHER_MAX (use with the SCHED_OTHER policy) o PRI_FIFO_MIN <= priority <= PRI_FIFO_MAX (use with the SCHED_FIFO policy) o PRI_RR_MIN <= priority <= PRI_RR_MAX (use with the SCHED_RR policy) o PRI_FG_MIN_NP <= priority <= PRI_FG_MAX_NP (use with the SCHED_FG_NP policy) o PRI_BG_MIN_NP <= priority <= PRI_BG_MAX_NP (use with the SCHED_BG_NP policy) The default priority is the midpoint between PRI_OTHER_MIN and PRI_OTHER_MAX. To specify a minimum or maximum priority, use the appropriate symbol; for example, PRI_FIFO_MIN or PRI_FIFO_MAX. To specify a value between the minimum and maximum, use an appropriate arithmetic expression. For example, to specify a priority midway between the minimum and maximum for the Round Robin scheduling policy, specify the following concept using your programming language's syntax: pri_rr_mid = (PRI_RR_MIN + PRI_RR_MAX)/2 If your expression results in a value outside the range of minimum to maximum, an error results when you attempt to use it. DESCRIPTION The pthread_attr_setprio() routine sets the execution priority of threads that are created using the attributes object specified by the attr parameter. By default, a created thread inherits the priority of the thread calling pthread_create(). To specify a priority using this routine, scheduling inheritance must be disabled at the time the thread is created. Before calling this routine and pthread_create(), call pthread_attr_setinheritsched() and specify the value PTHREAD_DEFAULT_SCHED for the inherit parameter. An application specifies priority only to express the urgency of execut- ing the thread relative to other threads. Priority is not used to con- trol mutual exclusion when accessing shared data. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description ___________________________________________________________ 0 Successful completion. -1 [EINVAL] The value specified by attr is invalid. -1 [ERANGE] One or more parameters supplied have an invalid value. -1 [EPERM] The caller does not have the appropriate privileges to set the priority of the specified thread. RELATED INFORMATION FUNCTIONS: pthread_attr_create pthread_attr_getprio pthread_attr_setinheritsched pthread_create 4 pthread_attr_setsched NAME pthread_attr_setsched - Changes the scheduling policy attribute of thread creation SYNOPSIS #include int pthread_attr_setsched( pthread_attr_t *attr int *scheduler ); PARAMETERS attr Thread attributes object modified. scheduler New value for the scheduling policy attribute. Valid values are as follows: SCHED_FIFO (First In, First Out) The highest-priority thread runs until it blocks. If there is more than one thread with the same priority, and that priority is the highest among other threads, the first thread to begin running continues until it blocks. SCHED_RR (Round Robin) The highest-priority thread runs until it blocks; however, threads of equal priority, if that priority is the highest among other threads, are timesliced. Timeslicing is a process in which threads alternate using available processors. SCHED_OTHER (Default) All threads are timesliced. SCHED_OTHER ensures that all threads, regardless of priority, receive some scheduling so that no thread is completely denied execution time. (However, SCHED_OTHER threads can be denied execution time by SCHED_FIFO or SCHED_RR threads.) SCHED_FG_NP (Foreground) Same as SCHED_OTHER. Threads are time- sliced and priorities can be modified dynamically by the scheduler to ensure fairness. SCHED_BG_NP (Background) Ensures that all threads, regardless of priority, receive some scheduling. However, SCHED_BG_NP can be denied execution by SCHED_FIFO or SCHED_RR threads. DESCRIPTION The pthread_attr_setsched() routine sets the scheduling policy of a thread that is created using the attributes object specified by the attr parameter. The default value of the scheduling attribute is SCHED_OTHER. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description ___________________________________________________________ 0 Successful completion. -1 [EINVAL] The value specified by attr is invalid. -1 [EINVAL] The value specified by scheduler is invalid. -1 [EPERM] The caller does not have the appropriate privileges to set the priority of the specified thread. RELATED INFORMATION FUNCTIONS: pthread_attr_create pthread_attr_getsched pthread_attr_setinheritsched pthread_create 4 pthread_attr_setstacksize NAME pthread_attr_setstacksize - Changes the stacksize attribute of thread creation SYNOPSIS #include int pthread_attr_setstacksize( pthread_attr_t *attr, long stacksize ); PARAMETERS attr Thread attributes object modified. stacksize New value for the stacksize attribute. The stacksize parameter specifies the minimum size (in bytes) of the stack needed for a thread. DESCRIPTION The pthread_attr_setstacksize() routine sets the minimum size (in bytes) of the stack needed for a thread created using the attributes object specified by the attr parameter. Use this routine to adjust the size of the writable area of the stack. The default value of the stacksize attribute is machine specific. A thread's stack is fixed at the time of thread creation. Only the main or initial thread can dynamically extend its stack. Most compilers do not check for stack overflow. Ensure that your thread stack is large enough for anything that you call from the thread. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description ___________________________________________________________ 0 Successful completion. -1 [EINVAL] The value specified by attr is invalid. -1 [EINVAL] The value specified by stacksize is invalid. RELATED INFORMATION FUNCTIONS: pthread_attr_create pthread_attr_getstacksize pthread_create 4 pthread_cancel NAME pthread_cancel - Allows a thread to request that it or another thread terminate execution SYNOPSIS #include int pthread_cancel(pthread_t thread); PARAMETERS thread Thread that receives a cancel request. DESCRIPTION The pthread_cancel() routine sends a cancel to the specified thread. A cancel is a mechanism by which a calling thread informs either itself or the called thread to terminate as quickly as possible. Issuing a cancel does not guarantee that the canceled thread receives or handles the can- cel. The canceled thread can delay processing the cancel after receiving it. For instance, if a cancel arrives during an important operation, the canceled thread can continue if what it is doing cannot be interrupted at the point where the cancel is requested. Because of communications delays, the calling thread can only rely on the fact that a cancel eventually becomes pending in the designated thread (provided that the thread does not terminate beforehand). Furth- ermore, the calling thread has no guarantee that a pending cancel is to be delivered because delivery is controlled by the designated thread. Termination processing when a cancel is delivered to a thread is similar to pthread_exit(). Outstanding cleanup routines are executed in the con- text of the target thread, and a status of -1 is made available to any threads joining with the target thread. This routine is preferred in implementing Ada's abort statement and any other language (or software-defined construct) for requesting thread cancellation. The results of this routine are unpredictable if the value specified in thread refers to a thread that does not currently exist. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description ____________________________________________________ 0 Successful completion. -1 [EINVAL] The specified thread is invalid. -1 [ERSCH] The specified thread does not refer to a currently existing thread. RELATED INFORMATION FUNCTIONS: pthread_exit pthread_join pthread_setasynccancel pthread_setcancel pthread_testcancel 4 pthread_cleanup_pop NAME pthread_cleanup_pop - Removes the cleanup handler at the top of the cleanup stack and optionally executes it SYNOPSIS #include void pthread_cleanup_pop(int execute); PARAMETERS execute Integer that specifies whether the cleanup routine that is popped should be executed or just discarded. If the value is nonzero, the cleanup routine is executed. DESCRIPTION The pthread_cleanup_pop() routine removes the routine specified in pthread_cleanup_push() from the top of the calling thread's cleanup stack and executes it if the value specified in execute is nonzero. This routine and pthread_cleanup_push() are implemented as macros and must be displayed as statements and in pairs within the same lexical scope. You can think of the pthread_cleanup_push() macro as expanding to a string whose first character is a { (left brace) and pthread_cleanup_pop as expanding to a string containing the correspond- ing } (right brace). RETURN VALUES This routine must be used as a statement. RELATED INFORMATION FUNCTIONS: pthread_cleanup_push 4 pthread_cleanup_push NAME pthread_cleanup_push - Establishes a cleanup handler SYNOPSIS #include void pthread_cleanup_push( void routine, pthread_addr_t arg ); PARAMETERS routine Routine executed as the cleanup handler. arg Parameter executed with the cleanup routine. DESCRIPTION The pthread_cleanup_push() routine pushes the specified routine onto the calling thread's cleanup stack. The cleanup routine is popped from the stack and executed with the arg parameter when any of the following actions occur: o The thread calls pthread_exit(). o The thread is canceled. o The thread calls pthread_cleanup_pop() and specifies a nonzero value for the execute parameter. This routine and pthread_cleanup_pop() are implemented as macros and must be displayed as statements and in pairs within the same lexical scope. You can think of the pthread_cleanup_push() macro as expanding to a string whose first character is a { (left brace) and pthread_cleanup_pop() as expanding to a string containing the corresponding } (right brace). RETURN VALUES This routine must be used as a statement. RELATED INFORMATION FUNCTIONS: pthread_cancel pthread_cleanup_pop pthread_exit pthread_testcancel 4 pthread_condattr_create NAME pthread_condattr_create - Creates a condition variable attributes object SYNOPSIS #include int pthread_condattr_create(pthread_condattr_t *attr); PARAMETERS attr Condition variable attributes object that is created. DESCRIPTION The pthread_condattr_create() routine creates a condition variable attributes object that is used to specify the attributes of condition variables when they are created. The condition variable attributes object is initialized with the default value for all of the attributes defined by a given implementation. When a condition variable attributes object is used to create a condi- tion variable, the values of the individual attributes determine the characteristics of the new object. Attributes objects act like addi- tional parameters to object creation. Changing individual attributes does not affect objects that were previously created using the attri- butes object. RETURN VALUES The created condition variable attributes object is returned to the attr parameter. If the function fails, errno may be set to one of the following values: Return Error Description ___________________________________________________________ 0 Successful completion. -1 [EINVAL] The value specified by attr is invalid. -1 [ENOMEM] Insufficient memory exists to create the condition variable attributes object. RELATED INFORMATION FUNCTIONS: pthread_condattr_delete pthread_cond_init 4 pthread_condattr_delete NAME pthread_condattr_delete - Deletes a condition variable attributes object SYNOPSIS #include int pthread_condattr_delete(pthread_condattr_t *attr); PARAMETERS attr Condition variable attributes object deleted. DESCRIPTION The pthread_condattr_delete() routine deletes a condition variable attributes object. Call this routine when a condition variable attri- butes object created by pthread_condattr_create() is no longer refer- enced. This routine gives permission to reclaim storage for the condition vari- able attributes object. Condition variables that are created using this attributes object are not affected by the deletion of the condition variable attributes object. The results of calling this routine are unpredictable if the handle specified by the attr parameter refers to an attributes object that does not exist. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description ___________________________________________________________ 0 Successful completion. -1 [EINVAL] The value specified by attr is invalid. RELATED INFORMATION FUNCTIONS: pthread_condattr_create 4 pthread_cond_broadcast NAME pthread_cond_broadcast - Wakes all threads that are waiting on a condition variable SYNOPSIS #include int pthread_cond_broadcast(pthread_cond_t *cond); PARAMETERS cond Condition variable broadcast. DESCRIPTION The pthread_cond_broadcast() routine wakes all threads waiting on a con- dition variable. Calling this routine implies that data guarded by the associated mutex has changed so that it might be possible for one or more waiting threads to proceed. If any one waiting thread might be able to proceed, call pthread_cond_signal(). Call this routine when the associated mutex is either locked or unlocked. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description ___________________________________________________________ 0 Successful completion. -1 [EINVAL] The value specified by cond is invalid. RELATED INFORMATION FUNCTIONS: pthread_cond_destroy pthread_cond_init pthread_cond_signal pthread_cond_timedwait pthread_cond_wait 4 pthread_cond_destroy NAME pthread_cond_destroy - Deletes a condition variable SYNOPSIS #include int pthread_cond_destroy(pthread_cond_t *cond); PARAMETERS cond Condition variable deleted. DESCRIPTION The pthread_cond_destroy() routine deletes a condition variable. Call this routine when a condition variable is no longer referenced. The effect of calling this routine is to give permission to reclaim storage for the condition variable. The results of this routine are unpredictable if the condition variable specified in cond does not exist. The results of this routine are also unpredictable if there are threads waiting for the specified condition variable to be signaled or broadcast when it is deleted. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description ___________________________________________________________ 0 Successful completion. -1 [EINVAL] The value specified by cond is invalid. -1 [EBUSY] A thread is currently executing a pthread_cond_timedwait() routine or pthread_cond_wait() on the condition variable specified in cond. RELATED INFORMATION FUNCTIONS: pthread_cond_broadcast pthread_cond_init pthread_cond_signal pthread_cond_timedwait pthread_cond_wait 4 pthread_cond_init NAME pthread_cond_init - Creates a condition variable SYNOPSIS #include int pthread_cond_init( pthread_cond_t *cond, pthread_condattr_t attr ); PARAMETERS cond Condition variable that is created. attr Condition variable attributes object that defines the characteristics of the condition variable created. If you specify pthread_condattr_default, default attributes are used. DESCRIPTION The pthread_cond_init() routine creates and initializes a condition variable. A condition variable is a synchronization object used in con- junction with a mutex. A mutex controls access to shared data; a condi- tion variable allows threads to wait for that data to enter a defined state. The state is defined by a Boolean expression called a predicate. A condition variable is signaled or broadcast to indicate that a predi- cate might have become true. The broadcast operation indicates that all waiting threads need to resume and reevaluate the predicate. The signal operation is used when any one waiting thread can continue. If a thread that holds a mutex determines that the shared data is not in the correct state for it to proceed (the associated predicate is not true), it waits on a condition variable associated with the desired state. Waiting on the condition variable automatically releases the mutex so that other threads can modify or examine the shared data. When a thread modifies the state of the shared data so that a predicate might be true, it signals or broadcasts on the appropriate condition variable so that threads waiting for that predicate can continue. It is important that all threads waiting on a particular condition vari- able at any time hold the same mutex. If they do not, the behavior of the wait operation is unpredictable (an implementation can use the mutex to control internal access to the condition variable object). However, it is legal for a client to store condition variables and mutexes and later reuse them in different combinations. The client must ensure that no threads use the condition variable with the old mutex. At any time, an arbitrary number of condition variables can be associated with a sin- gle mutex, each representing a different predicate of the shared data protected by that mutex. Condition variables are not owned by a particular thread. Any associated storage is not automatically deallocated when the creating thread ter- minates. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description __________________________________________________ 0 Successful completion. -1 [EAGAIN] The system lacks the necessary resources to initialize another condition variable. -1 [EINVAL] Invalid attributes object. -1 [ENOMEM] Insufficient memory exists to initialize the condition variable. RELATED INFORMATION FUNCTIONS: pthread_cond_broadcast pthread_cond_destroy pthread_cond_signal pthread_cond_timedwait pthread_cond_wait 4 pthread_cond_signal NAME pthread_cond_signal - Wakes one thread that is waiting on a condition variable SYNOPSIS #include int pthread_cond_signal(pthread_cond_t *cond); PARAMETERS cond Condition variable signaled. DESCRIPTION The pthread_cond_signal() routine wakes one thread waiting on a condi- tion variable. Calling this routine implies that data guarded by the associated mutex has changed so that it is possible for a single waiting thread to proceed. Call this routine when any thread waiting on the specified condition variable might find its predicate true, but only one thread needs to proceed. The scheduling policy determines which thread is awakened. For policies SCHED_FIFO and SCHED_RR a blocked thread is chosen in priority order. Call this routine when the associated mutex is either locked or unlocked. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description ___________________________________________________________ 0 Successful completion. -1 [EINVAL] The value specified by cond is invalid. RELATED INFORMATION FUNCTIONS: pthread_cond_broadcast pthread_cond_destroy pthread_cond_init pthread_cond_timedwait pthread_cond_wait 4 pthread_cond_timedwait NAME pthread_cond_timedwait - Causes a thread to wait for a condition variable to be signaled or broadcast SYNOPSIS #include int pthread_cond_timedwait( pthread_cond_t *cond, pthread_mutex_t *mutex, struct timespec *abstime ); PARAMETERS cond Condition variable waited on. mutex Mutex associated with the condition variable specified in cond. abstime Absolute time at which the wait expires, if the condition has not been signaled or broadcast. (See the pthread_get_expiration_np() routine, which you can use to obtain a value for this parameter.) DESCRIPTION The pthread_cond_timedwait() routine causes a thread to wait until one of the following occurs: o The specified condition variable is signaled or broadcast. o The current system clock time is greater than or equal to the time specified by the abstime parameter. This routine is identical to pthread_cond_wait() except that this rou- tine can return before a condition variable is signaled or broadcast- specifically, when a specified time expires. If the current time equals or exceeds the expiration time, this routine returns immediately, without causing the current thread to wait. Call this routine after you lock the mutex specified in mutex. The results of this routine are unpredictable if this routine is called without first locking the mutex. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description ___________________________________________________________ 0 Successful completion. -1 [EINVAL] The value specified by cond, mutex, or abstime is invalid. -1 [EAGAIN] The time specified by abstime expired. -1 [EDEADLK] A deadlock condition is detected. RELATED INFORMATION FUNCTIONS: pthread_cond_broadcast pthread_cond_destroy pthread_cond_init pthread_cond_signal pthread_cond_wait pthread_get_expiration_np 4 pthread_cond_wait NAME pthread_cond_wait - Causes a thread to wait for a condition variable to be signaled or broadcast SYNOPSIS #include int pthread_cond_wait( pthread_cond_t *cond, pthread_mutex_t *mutex ); PARAMETERS cond Condition variable waited on. mutex Mutex associated with the condition variable specified in cond. DESCRIPTION The pthread_cond_wait() routine causes a thread to wait for a condition variable to be signaled or broadcast. Each condition corresponds to one or more predicates based on shared data. The calling thread waits for the data to reach a particular state (for the predicate to become true). Call this routine after you have locked the mutex specified in mutex. The results of this routine are unpredictable if this routine is called without first locking the mutex. This routine automatically releases the mutex and causes the calling thread to wait on the condition. If the wait is satisfied as a result of some thread calling pthread_cond_signal() or pthread_cond_broadcast(), the mutex is reacquired and the routine returns. A thread that changes the state of storage protected by the mutex in such a way that a predicate associated with a condition variable might now be true must call either pthread_cond_signal() or pthread_cond_broadcast() for that condition variable. If neither call is made, any thread waiting on the condition variable continues to wait. This routine might (with low probability) return when the condition variable has not been signaled or broadcast. When a spurious wakeup occurs, the mutex is reacquired before the routine returns. (To handle this type of situation, enclose this routine in a loop that checks the predicate.) RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description _________________________________________________________________ 0 Successful completion. -1 [EINVAL] The value specified by cond or mutex is invalid. -1 [EDEADLK] A deadlock condition is detected. RELATED INFORMATION FUNCTIONS: pthread_cond_broadcast pthread_cond_destroy pthread_cond_init pthread_cond_signal pthread_cond_timedwait 4 pthread_create NAME pthread_create - Creates a thread object and thread SYNOPSIS #include int pthread_create( pthread_t *thread, pthread_attr_t attr, pthread_startroutine_t start_routine, pthread_addr_t arg ); PARAMETERS thread Handle to the thread object created. attr Thread attributes object that defines the characteristics of the thread being created. If you specify pthread_attr_default, default attributes are used. start_routine Function executed as the new thread's start routine. arg Address value copied and passed to the thread's start routine. DESCRIPTION The pthread_create() routine creates a thread object and a thread. A thread is a single, sequential flow of control within a program. It is the active execution of a designated routine, including any nested rou- tine invocations. A thread object defines and controls the executing thread. CREATING A THREAD Calling this routine sets into motion the following actions: o An internal thread object is created to describe the thread. o The associated executable thread is created with attributes specified by the attr parameter (or with default attributes if pthread_attr_default is specified). o The thread parameter receives the new thread. o The start_routine function is called when this routine completes successfully. THREAD EXECUTION The thread is created in the ready state and therefore might immediately begin executing the function specified by the start_routine parameter. The newly created thread begins running before pthread_create() completes if the new thread follows the SCHED_RR or SCHED_FIFO scheduling policy or has a priority higher than the creating thread, or both. Otherwise, the new thread begins running at its turn, which with sufficient processors might also be before pthread_create() returns. The start_routine parameter is passed a copy of the arg parameter. The value of the arg parameter is unspecified. The thread object exists until the pthread_detach() routine is called or the thread terminates, whichever occurs last. The synchronization between the caller of pthread_create() and the newly created thread is through the use of the pthread_join() routine (or any other mutexes or condition variables they agree to use). TERMINATING A THREAD A thread terminates when one of the following events occurs: o The thread returns from its start routine. o The thread exits (within a routine) as the result of calling the pthread_exit() routine. o The thread is canceled. WHEN A THREAD TERMINATES The following actions are performed when a thread terminates: o If the thread terminates by returning from its start routine or calling pthread_exit(), the return value is copied into the thread object. If the start routine returns normally and the start routine is a procedure that does not return a value, then the result obtained by pthread_join() is unpredictable. If the thread has been cancelled, a return value of -1 is copied into the thread object. The return value can be retri- -eved by other threads by calling the pthread_join() routine. o A destructor for each thread-specific data point is removed from the list of destructors for this thread and then is called. This step destroys all the thread-specific data associated with the current thread. o Each cleanup handler that has been declared by pthread_cleanup_push() and not yet removed by pthread_cleanup_pop() is called. The most recently pushed handler is called first. o A flag is set in the thread object indicating that the thread has terminated. This flag must be set in order for callers of pthread_join() to return from the call. o A broadcast is made so that all threads currently waiting in a call to pthread_join() can return from the call. o The thread object is marked to indicate that it is no longer needed by the thread itself. A check is made to determine if the thread object is no longer needed by other threads; that is, if pthread_detach() has been called. If that routine is called, then the thread object is deallocated. RETURN VALUES Upon successful completion, this routine stores the identifier of the created thread at thread and returns 0. Otherwise, a value of -1 is returned and no thread is created, the contents of thread are undefined, and errno may be set to one of the following values: Return Error Description __________________________________________________ 0 Successful completion. -1 [EAGAIN] The system lacks the necessary resources to create another thread. -1 [ENOMEM] Insufficient memory exists to create the thread object. This is not a temporary condition. RELATED INFORMATION FUNCTIONS: pthread_attr_create pthread_cancel pthread_detach pthread_exit pthread_join 4 pthread_delay_np NAME pthread_delay_np - Causes a thread to wait for a specified period SYNOPSIS #include int pthread_delay_np( struct timespec *interval ); PARAMETERS interval Number of seconds and nanoseconds that the calling thread waits before continuing execution. The value specified must be greater than or equal to 0 (zero). DESCRIPTION The pthread_delay_np() routine causes a thread to delay execution for a specified period of elapsed wall clock time. The period of time the thread waits is at least as long as the number of seconds and nanoseconds specified in the interval parameter. Specifying an interval of 0 seconds and 0 nanoseconds is allowed and can result in the thread giving up the processor or delivering a pending cancel. The struct timespec structure contains two fields, as follows: o The tv_sec field is an integer number of seconds. o The tv_nsec field is an integer number of nanoseconds. This routine is not portable. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description _______________________________________________________________ 0 Successful completion. -1 [EINVAL] The value specified by interval is invalid. RELATED INFORMATION FUNCTIONS: pthread_yield 4 pthread_detach NAME pthread_detach - Marks a thread object for deletion SYNOPSIS #include int pthread_detach( pthread_t *thread ); PARAMETERS thread Thread object marked for deletion. DESCRIPTION The pthread_detach() routine indicates that storage for the specified thread is reclaimed when the thread terminates. This includes storage for the thread parameter's return value. If thread has not terminated when this routine is called, this routine does not cause it to ter- minate. Call this routine when a thread object is no longer referenced. Addi- tionally, call this routine for every thread that is created to ensure that storage for thread objects does not accumulate. You cannot join with a thread after the thread has been detached. The results of this routine are unpredictable if the value of thread refers to a thread object that does not exist. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description _____________________________________________________________ 0 Successful completion. -1 [EINVAL] The value specified by thread is invalid. -1 [ESRCH] The value specified by thread does not refer to an existing thread. RELATED INFORMATION FUNCTIONS: pthread_cancel pthread_create pthread_exit pthread_join 4 pthread_equal NAME pthread_equal - Compares one thread identifier to another thread identifier. SYNOPSIS #include equal = pthread_equal( pthread_t *thread1, pthread_t thread2 ); PARAMETERS thread1 The first thread identifier to be compared. thread2 The second thread identifier to be compared. DESCRIPTION This routine compares one thread identifier to another thread identi- -fier.(This routine does not check whether the objects that corres- -pond to the identifiers currently exist.) If the identifiers have values indicating that they designate the same object, 1 (true) is returned. If the values do not designate the same object, 0 (false) is returned. This routine is implemented as a C macro. RETURN VALUES Possible return values are as follows: Return Error Description __________________________________________________ 0 Values of thread1 and thread2 do not designate the same object. 1 Values of thread1 and thread2 designate the same object. EXAMPLES equal = pthread_equal (thread1, thread2) RELATED INFORMATION FUNCTIONS: pthread_create 4 pthread_exit NAME pthread_exit - Terminates the calling thread SYNOPSIS #include void pthread_exit( pthread_addr_t status ); PARAMETERS status Address value copied and returned to the caller of pthread_join(). DESCRIPTION The pthread_exit() routine terminates the calling thread and makes a status value available to any thread that calls pthread_join() and specifies the terminating thread. An implicit call to pthread_exit() is issued when a thread returns from the start routine that was used to create it. The function's return value serves as the thread's exit status. If the return value is -1, an error exit is forced for the thread instead of a normal exit. The pro- cess exits when the last running thread calls pthread_exit(), with an undefined exit status. RESTRICTIONS The pthread_exit() routine does not work in the main (initial) thread because DCE Threads relies on information at the base of thread stacks; this information does not exist in the main thread. RETURN VALUES No value is returned. RELATED INFORMATION FUNCTIONS: pthread_create pthread_detach pthread_join 4 pthread_getprio NAME pthread_getprio - Obtains the current priority of a thread SYNOPSIS #include int pthread_getprio( pthread_t thread ); PARAMETERS thread Thread whose priority is obtained. DESCRIPTION The pthread_getprio() routine obtains the current priority of a thread. The current priority is different from the initial priority of the thread if the pthread_setprio() routine is called. The exact effect of different priority values depends upon the schedul- ing policy assigned to the thread. RETURN VALUES The current priority value of the thread specified in thread is returned. (See the pthread_setprio() reference page for valid values.) If the function fails, errno may be set to one of the following values: Return Error Description ________________________________________________________ Priority value Successful completion. -1 [EINVAL] The value specified by thread is invalid. -1 [ESRCH] The value specified by thread does not refer to an existing thread. RELATED INFORMATION FUNCTIONS: pthread_attr_setprio pthread_setprio pthread_setscheduler 4 pthread_getscheduler NAME pthread_getscheduler - Obtains the current scheduling policy of a thread SYNOPSIS #include int pthread_getscheduler( pthread_t thread ); PARAMETERS thread Thread whose scheduling policy is obtained. DESCRIPTION The pthread_getscheduler() routine obtains the current scheduling policy of a thread. The current scheduling policy of a thread is different from the initial scheduling policy if the pthread_setscheduler() routine is called. RETURN VALUES The current scheduling policy value of the thread specified in thread is returned. (See the pthread_setscheduler() reference page for valid values.) If the function fails, errno may be set to one of the following values: Return Error Description ______________________________________________________________ Current scheduling policy Successful completion. -1 [EINVAL] The value specified by thread is invalid. -1 [ESRCH] The value specified by thread does not refer to an existing thread. RELATED INFORMATION FUNCTIONS: pthread_attr_setscheduler pthread_setscheduler 4 pthread_getspecific NAME pthread_getspecific - Obtains the thread-specific data associated with the specified key SYNOPSIS #include int pthread_getspecific( pthread_key_t key, pthread_addr_t *value ); PARAMETERS key Context key value that identifies the data value obtained. This key value must be obtained from pthread_keycreate(). value Address of the current thread-specific data value associated with the specified key. DESCRIPTION The pthread_getspecific() routine obtains the thread-specific data asso- ciated with the specified key for the current thread. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description _____________________________________________ 0 Successful completion. -1 [EINVAL] The key value is invalid. RELATED INFORMATION FUNCTIONS: pthread_keycreate pthread_setspecific 4 pthread_get_expiration_np NAME pthread_get_expiration_np - Obtains a value representing a desired expiration time SYNOPSIS #include int pthread_get_expiration_np( struct timespec *delta, struct timespec *abstime ); PARAMETERS delta Number of seconds and nanoseconds to add to the current system time. The result is the time when a timed wait expires. abstime Value representing the expiration time. DESCRIPTION The pthread_get_expiration_np() routine adds a specified interval to the current absolute system time and returns a new absolute time. This new absolute time is used as the expiration time in a call to pthread_cond_timedwait(). This routine is not portable. The struct timespec structure contains two fields, as follows: o The tv_sec field is an integer number of seconds. o The tv_nsec field is an integer number of nanoseconds. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description ____________________________________________________________ 0 Successful completion. -1 [EINVAL] The value specified by delta is invalid. RELATED INFORMATION FUNCTIONS: pthread_cond_timedwait 4 pthread_join NAME pthread_join - Causes the calling thread to wait for the termination of a specified thread SYNOPSIS #include int pthread_join( pthread_t thread, pthread_addr_t *status ); PARAMETERS thread Thread whose termination is awaited by the caller of this routine. status Status value of the terminating thread when that thread calls pthread_exit(). DESCRIPTION The pthread_join() routine causes the calling thread to wait for the termination of a specified thread. A call to this routine returns after the specified thread has terminated. Any number of threads can call this routine. All threads are awakened when the specified thread terminates. If the current thread calls this routine, a deadlock results. The results of this routine are unpredictable if the value for thread refers to a thread object that no longer exists. RETURN VALUES If the thread terminates normally, the exit status is the value that is is optionally returned from the thread's start routine. If the function fails, errno may be set to one of the following values: Return Error Description ______________________________________________________________ 0 Successful completion. -1 [EINVAL] The value specified by thread is invalid. -1 [ESRCH] The value specified by thread does not refer to a currently existing thread. -1 [EDEADLK] A deadlock is detected. RELATED INFORMATION FUNCTIONS: pthread_create pthread_detach pthread_exit 4 pthread_keycreate NAME pthread_keycreate - Generates a unique thread-specific data key value SYNOPSIS #include int pthread_keycreate( pthread_key_t *key, pthread_destructor_t destructor ); PARAMETERS key Value of the new thread-specific data key. destructor Procedure to be called to destroy a data value associated with the created key when the thread terminates. DESCRIPTION The pthread_keycreate() routine generates a unique thread-specific data key value. This key value identifies a thread-specific data value, which is an address of memory generated by the client containing arbitrary data of any size. Thread-specific data allows client software to associate information with the current thread. For example, thread-specific data can be used by a language runtime library that needs to associate a language-specific thread-private data structure with an individual thread. The thread-specific data routines also provide a portable means of implementing the class of storage called thread-private static, which is needed to support parallel decomposition in the FORTRAN language. This routine generates and returns a new key value. Each call to this routine within a process returns a key value that is unique within an application invocation. Calls to pthread_keycreate() must occur in ini- tialization code guaranteed to execute only once in each process. The pthread_once() routine provides a way of specifying such code. When multiple facilities share access to thread-specific data, the facilities must agree on the key value that is associated with the con- text. The key value must be created only once and needs to be stored in a location known to each facility. (It may be desirable to encapsulate the creation of a key, and the setting and getting of context values for that key, within a special facility created for that purpose.) When a thread terminates, thread-specific data is automatically des- troyed. For each thread-specific data currently associated with the thread, the destructor routine associated with the key value of that context is called. The order in which per-thread context destructors are called at thread termination is undefined. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description _________________________________________________________________ 0 Successful completion. -1 [EINVAL] The value specified by key is invalid. -1 [EAGAIN] An attempt was made to allocate a key when the key namespace is exhausted. This is not a temporary condition. -1 [ENOMEM] Insufficient memory exists to create the key. RELATED INFORMATION FUNCTIONS: pthread_getspecific pthread_setspecific 4 pthread_lock_global_np NAME pthread_lock_global_np - Locks the global mutex SYNOPSIS #include void pthread_lock_global_np(); DESCRIPTION The pthread_lock_global_np() routine locks the global mutex. If the glo- bal mutex is currently held by another thread when a thread calls this routine, the thread waits for the global mutex to become available. The thread that has locked the global mutex becomes its current owner and remains the owner until the same thread has unlocked it. This rou- tine returns with the global mutex in the locked state and with the current thread as the global mutex's current owner. Use the global mutex when calling a library package that is not designed to run in a multithreaded environment. (Unless the documentation for a library function specifically states that it is compatible with mul- tithreading, assume that it is not compatible; in other words, assume it is nonreentrant.) The global mutex is one lock. Any code that calls any function that is not known to be reentrant uses the same lock. This prevents dependencies among threads calling library functions and those functions calling other functions, and so on. The global mutex is a recursive mutex. A thread that has locked the glo- bal mutex can relock it without deadlocking. (The locking thread must call pthread_unlock_global_np() as many times as it called this routine to allow another thread to lock the global mutex.) This routine is not portable. RETURN VALUES No value is returned. RELATED INFORMATION FUNCTIONS: pthread_mutexattr_setkind_np pthread_mutex_lock pthread_mutex_unlock pthread_unlock_global_np 4 pthread_mutexattr_create NAME pthread_mutexattr_create - Creates a mutex attributes object SYNOPSIS #include int pthread_mutexattr_create( pthread_mutexattr_t *attr ); PARAMETERS attr Mutex attributes object created. DESCRIPTION The pthread_mutexattr_create() routine creates a mutex attributes object used to specify the attributes of mutexes when they are created. The mutex attributes object is initialized with the default value for all of the attributes defined by a given implementation. When a mutex attributes object is used to create a mutex, the values of the individual attributes determine the characteristics of the new object. Attributes objects act like additional parameters to object creation. Changing individual attributes does not affect any objects that were previously created using the attributes object. RETURN VALUES The created mutex attributes object is returned to the attr parameter. If the function fails, errno may be set to one of the following values: Return Error Description ___________________________________________________ 0 Successful completion. -1 [EINVAL] The value specified by attr is invalid. -1 [ENOMEM] Insufficient memory exists to create the mutex attributes object. RELATED INFORMATION FUNCTIONS: pthread_create pthread_mutexattr_delete pthread_mutexattr_getkind_np pthread_mutexattr_setkind_np pthread_mutex_init 4 pthread_mutexattr_delete NAME pthread_mutexattr_delete - Deletes a mutex attributes object SYNOPSIS #include int pthread_mutexattr_delete( pthread_mutexattr_t *attr ); PARAMETERS attr Mutex attributes object deleted. DESCRIPTION The pthread_mutexattr_delete() routine deletes a mutex attributes object. Call this routine when a mutex attributes object is no longer referenced by the pthread_mutexattr_create() routine. This routine gives permission to reclaim storage for the mutex attri- butes object. Mutexes that were created using this attributes object are not affected by the deletion of the mutex attributes object. The results of calling this routine are unpredictable if the attributes object specified in the attr parameter does not exist. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description ___________________________________________________________ 0 Successful completion. -1 [EINVAL] The value specified by attr is invalid. RELATED INFORMATION FUNCTIONS: pthread_mutexattr_create 4 pthread_mutexattr_getkind_np NAME pthread_mutexattr_getkind_np - Obtains the mutex type attribute used when a mutex is created SYNOPSIS #include int pthread_mutexattr_getkind_np( pthread_mutexattr_t *attr ); PARAMETERS attr Mutex attributes object whose mutex type is obtained. DESCRIPTION The pthread_mutexattr_getkind_np() routine obtains the mutex type attribute that is used when a mutex is created. See the pthread_mutexattr_setkind_np() reference page for information about mutex type attributes. This routine is not portable. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description ______________________________________________________________ Mutex type attribute Successful completion. -1 [EINVAL] The value specified by attr is invalid. RELATED INFORMATION FUNCTIONS: pthread_mutexattr_create pthread_mutexattr_setkind_np pthread_mutex_init 4 pthread_mutexattr_setkind_np NAME pthread_mutexattr_setkind_np - Specifies the mutex type attribute SYNOPSIS #include int pthread_mutexattr_setkind_np( pthread_mutexattr_t *attr, int kind ); PARAMETERS attr Mutex attributes object modified. kind New value for the mutex type attribute. The kind parameter specifies the type of mutex that is created. Valid values are MUTEX_FAST_NP (default), MUTEX_RECURSIVE_NP, and MUTEX_NONRECURSIVE_NP. DESCRIPTION The pthread_mutexattr_setkind_np() routine sets the mutex type attribute that is used when a mutex is created. A fast mutex is locked and unlocked in the fastest manner possible. A fast mutex can only be locked (obtained) once. All subsequent calls to pthread_mutex_lock() cause the calling thread to block until the mutex is freed by the thread that owns it. If the thread that owns the mutex attempts to lock it again, the thread waits for itself to release the mutex (causing a deadlock). A recursive mutex can be locked more than once by the same thread without causing that thread to deadlock. In other words, a single thread can make consecutive calls to pthread_mutex_lock() without blocking. The thread must then call pthread_mutex_unlock() the same number of times as it called pthread_mutex_lock() before another thread can lock the mutex. A nonrecursive mutex is locked only once by a thread, like a fast mutex. If the thread tries to lock the mutex again without first unlocking it, the thread receives an error. Thus, nonrecursive mutexes are more informative than fast mutexes because fast mutexes block in such a case, leaving it up to you to determine why the thread no longer executes. Also, if someone other than the owner tries to unlock a nonrecursive mutex, an error is returned. Never use a recursive mutex with condition variables because the impli- cit unlock performed for a pthread_cond_wait() or pthread_cond_timedwait() might not actually release the mutex. In that case, no other thread can satisfy the condition of the predicate. This routine is not portable. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description _____________________________________________________________ 0 Successful completion. -1 [EINVAL] The value specified by attr or kind is invalid. -1 [EPERM] The caller does not have the appropriate privileges. -1 [ERANGE] One or more parameters supplied have an invalid value. RELATED INFORMATION FUNCTIONS: pthread_mutexattr_create pthread_mutexattr_getkind_np pthread_mutex_init 4 pthread_mutex_destroy NAME pthread_mutex_destroy - Deletes a mutex SYNOPSIS #include int pthread_mutex_destroy( pthread_mutex_t *mutex ); PARAMETERS mutex Mutex to be deleted. DESCRIPTION The pthread_mutex_destroy() routine deletes a mutex and must be called when a mutex object is no longer referenced. The effect of calling this routine is to reclaim storage for the mutex object. It is illegal to delete a mutex that has a current owner (in other words, is locked). The results of this routine are unpredictable if the mutex object speci- fied in the mutex parameter does not currently exist. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description ________________________________________________________________ 0 Successful completion. -1 [EBUSY] An attempt was made to destroy a mutex that is locked. -1 [EINVAL] The value specified by mutex is invalid. RELATED INFORMATION FUNCTIONS: pthread_mutex_init pthread_mutex_lock pthread_mutex_trylock pthread_mutex_unlock 4 pthread_mutex_init NAME pthread_mutex_init - Creates a mutex SYNOPSIS #include int pthread_mutex_init( pthread_mutex_t *mutex, pthread_mutexattr_t attr ); PARAMETERS mutex Mutex that is created. attr Attributes object that defines the characteristics of the created mutex. If you specify pthread_mutexattr_default, default attributes are used. DESCRIPTION The pthread_mutex_init() routine creates a mutex and initializes it to the unlocked state. If the thread that called this routine terminates, the created mutex is not automatically deallocated, because it is con- sidered shared among multiple threads. RETURN VALUES If an error condition occurs, this routine returns -1, the mutex is not initialized, the contents of mutex are undefined, and errno may be set to one of the following values: Return Error Description __________________________________________________________ 0 Successful completion. -1 [EAGAIN] The system lacks the necessary resources to initialize another mutex. -1 [ENOMEM] Insufficient memory exists to initialize the mutex. RELATED INFORMATION FUNCTIONS: pthread_mutexattr_create pthread_mutexattr_getkind_np pthread_mutexattr_setkind_np pthread_mutex_lock pthread_mutex_trylock pthread_mutex_unlock 4 pthread_mutex_lock NAME pthread_mutex_lock - Locks an unlocked mutex SYNOPSIS #include int pthread_mutex_lock( pthread_mutex_t *mutex ); PARAMETERS mutex Mutex that is locked. DESCRIPTION The pthread_mutex_lock() routine locks a mutex. If the mutex is locked when a thread calls this routine, the thread waits for the mutex to become available. The thread that has locked a mutex becomes its current owner and remains the owner until the same thread has unlocked it. This routine returns with the mutex in the locked state and with the current thread as the mutex's current owner. If you specified a fast mutex in a call to pthread_mutexattr_setkind_np(), a deadlock can result if the current owner of a mutex calls this routine in an attempt to lock the mutex a second time. If you specified a recursive mutex in a call to pthread_mutexattr_setkind_np(), the current owner of a mutex can relock the same mutex without blocking. If you specify a nonrecursive mutex in a call to pthread_mutexattr_setkind_np(), an error is returned and the thread does not block if the current owner of a mutex calls this routine in an attempt to lock the mutex a second time. The preemption of a lower-priority thread that locks a mutex possibly results in the indefinite blocking of higher-priority threads waiting for the same mutex. The execution of the waiting higher-priority threads is blocked for as long as there is a sufficient number of runable threads of any priority between the lower-priority and higher-priority values. Priority inversion occurs when any resource is shared between threads with different priorities. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description _____________________________________________________________ 0 Successful completion. -1 [EINVAL] The value specified by mutex is invalid. -1 [EDEADLK] A deadlock condition is detected. RELATED INFORMATION FUNCTIONS: pthread_mutexattr_setkind_np pthread_mutex_destroy pthread_mutex_init pthread_mutex_trylock pthread_mutex_unlock 4 pthread_mutex_trylock NAME pthread_mutex_trylock - Locks a mutex SYNOPSIS #include int pthread_mutex_trylock( pthread_mutex_t *mutex ); PARAMETERS mutex Mutex that is locked. DESCRIPTION The pthread_mutex_trylock() routine locks a mutex. If the specified mutex is locked when a thread calls this routine, the calling thread does not wait for the mutex to become available. When a thread calls this routine, an attempt is made to lock the mutex immediately. If the mutex is successfully locked, 1 is returned and the current thread is then the mutex's current owner. If the mutex is locked by another thread when this routine is called, 0 (zero) is returned and the thread does not wait to acquire the lock. If a fast mutex is owned by the current thread, 0 is returned. If a recur- sive mutex is owned by the current thread, 1 is returned and the mutex is relocked. (To unlock a recursive mutex, each call to pthread_mutex_trylock() must be matched by a call to the pthread_mutex_unlock() routine.) RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description ____________________________________________________________ 1 Successful completion. 0 The mutex is locked; therefore, it was not acquired. -1 [EINVAL] The value specified by mutex is invalid. RELATED INFORMATION FUNCTIONS: pthread_mutexattr_setkind_np pthread_mutex_destroy pthread_mutex_init pthread_mutex_lock pthread_mutex_unlock 4 pthread_mutex_unlock NAME pthread_mutex_unlock - Unlocks a mutex SYNOPSIS #include int pthread_mutex_unlock( pthread_mutex_t *mutex ); PARAMETERS mutex Mutex that is unlocked. DESCRIPTION The pthread_mutex_unlock() routine unlocks a mutex. If no threads are waiting for the mutex, the mutex unlocks with no current owner. If one or more threads are waiting to lock the specified mutex, this routine causes one thread to return from its call to pthread_mutex_lock(). The scheduling policy is used to determine which thread acquires the mutex. For the SCHED_FIFO and SCHED_RR policies, a blocked thread is chosen in priority order. The results of calling this routine are unpredictable if the mutex specified in mutex is unlocked. The results of calling this routine are also unpredictable if the mutex specified in mutex is currently owned by a thread other than the calling thread. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description ____________________________________________________________ 0 Successful completion. -1 [EINVAL] The value specified by mutex is invalid. RELATED INFORMATION FUNCTIONS: pthread_mutexattr_setkind_np pthread_mutex_destroy pthread_mutex_init pthread_mutex_lock pthread_mutex_trylock pthread_unlock_global_np 4 pthread_once NAME pthread_once - Calls an initialization routine executed by one thread, a single time SYNOPSIS #include int pthread_once( pthread_once_t *once_block, pthread_initroutine_t init_routine ); PARAMETERS once_block Address of a record that defines the one-time initialization code. Each one-time initialization routine must have its own unique pthread_once_t data structure. init_routine Address of a procedure that performs the initialization. This routine is called only once, regardless of the number of times it and its associated once_block are passed to pthread_once(). DESCRIPTION The pthread_once() routine calls an initialization routine executed by one thread, a single time. This routine allows you to create your own initialization code that is guaranteed to be run only once, even if called simultaneously by multiple threads or multiple times in the same thread. For example, a mutex or a thread-specfic data key must be created exactly once. Calling pthread_once() prevents the code that creates a mutex or thread-specific data from being called by multiple threads. Without this routine, the execution must be serialized so that only one thread performs the initialization. Other threads that reach the same point in the code are delayed until the first thread is finished. ---------------------------- NOTE ------------------------------- If you specify an init_routine that directly or indirectly results in a recursive call to pthread_once() and that specifies the same init_routine argument, the recursive call can result in a deadlock. ------------------------------------------------------------------ This routine initializes the control record if it has not been initial- ized and then determines if the client one-time initialization routine has executed once. If it has not executed, this routine calls the ini- tialization routine specified in init_routine. If the client one-time initialization code has executed once, this routine returns. The pthread_once_t data structure is a record that allows client ini- tialization operations to guarantee mutual exclusion of access to the initialization routine, and that each initialization routine is executed exactly once. The client code must declare a variable of type pthread_once_t to use the client initialization operations. This variable must be initialized using the pthread_once_init macro, as follows: static pthread_once_t myOnceBlock = pthread_once_init; RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description __________________________________________ 0 Successful completion. -1 [EINVAL] Invalid parameter. 4 pthread_self NAME pthread_self - Obtains the identifier of the current thread SYNOPSIS #include pthread_t pthread_self(); DESCRIPTION The pthread_self() routine allows a thread to obtain its own identifier. For example, this identifier allows a thread to set its own priority. This value becomes meaningless when the thread object is deleted; that is, when the thread terminates its execution and pthread_detach() is called. RETURN VALUES Returns the identifier of the calling thread to pthread_t. RELATED INFORMATION FUNCTIONS: pthread_create pthread_setprio pthread_setscheduler 4 pthread_setasynccancel NAME pthread_setasynccancel - Enables or disables the current thread's asynchronous cancelability SYNOPSIS #include int pthread_setasynccancel( int state ); PARAMETERS state State of asynchronous cancelability set for the calling thread. On return, receives the prior state of asynchronous cancelability. Valid values are as follows: CANCEL_ON Asynchronous cancelability is enabled. CANCEL_OFF Asynchronous cancelability is disabled. DESCRIPTION The pthread_setasynccancel() routine enables or disables the current thread's asynchronous cancelability and returns the previous cancelabil- ity state to the state parameter. When general cancelability is set to CANCEL_OFF, a cancel cannot be delivered to the thread, even if a cancelable routine is called or asyn- chronous cancelability is enabled. When general cancelability is set to CANCEL_ON, cancelability depends on the state of the thread's asynchro- nous cancelability. When general cancelability is set to CANCEL_ON and asynchronous cancela- bility is set to CANCEL_OFF, the thread can only receive a cancel at specific cancellation points (for example, condition waits, thread joins, and calls to the pthread_testcancel() routine). If both general cancelability and asynchronous cancelability are set to CANCEL_ON, the thread can be canceled at any point in its execution. When a thread is created, the default asynchronous cancelability state is CANCEL_OFF. If you call this routine to enable asynchronous cancels, call it in a region of code where asynchronous delivery of cancels is disabled by a previous call to this routine. Do not call threads routines in regions of code where asynchronous delivery of cancels is enabled. The previous state of asynchronous delivery can be restored later by another call to this routine. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description ___________________________________________________________ CANCEL_ON Asynchronous cancelability was on. CANCEL_OFF Asynchronous cancelability was off. -1 [EINVAL] The specified state is not CANCEL_ON or CANCEL_OFF. RELATED INFORMATION FUNCTIONS: pthread_cancel pthread_setcancel pthread_testcancel 4 pthread_setcancel NAME pthread_setcancel - Enables or disables the current thread's general cancelability SYNOPSIS #include int pthread_setcancel( int state ); PARAMETERS state State of general cancelability set for the calling thread. On return, receives the prior state of general cancelability. Valid values are as follows: CANCEL_ON General cancelability is enabled. CANCEL_OFF General cancelability is disabled. DESCRIPTION The pthread_setcancel() routine enables or disables the current thread's general cancelability and returns the previous cancelability state to the state parameter. When general cancelability is set to CANCEL_OFF, a cancel cannot be delivered to the thread, even if a cancelable routine is called or asyn- chronous cancelability is enabled. When a thread is created, the default general cancelability state is CANCEL_ON. POSSIBLE DANGERS OF DISABLING CANCELABILITY The most important use of cancels is to ensure that indefinite wait operations are terminated. For example, a thread waiting on some network connection, which may take days to respond (or may never respond), is normally made cancelable. However, when cancelability is disabled, no routine is cancelable. Waits must be completed normally before a cancel can be delivered. As a result, the program stops working and the user is unable to cancel the operation. When disabling cancelability, be sure that no long waits can occur or that it is necessary for other reasons to defer cancels around that par- ticular region of code. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description ___________________________________________________________ CANCEL_ON Asynchronous cancelability was on. CANCEL_OFF Asynchronous cancelability was off. -1 [EINVAL] The specified state is not CANCEL_ON or CANCEL_OFF. RELATED INFORMATION FUNCTIONS: pthread_cancel pthread_setasynccancel pthread_testcancel 4 pthread_setprio NAME pthread_setprio - Changes the current priority of a thread SYNOPSIS #include int pthread_setprio( pthread_t thread, int priority ); PARAMETERS thread Thread whose priority is changed. priority New priority value of the thread specified in thread. The priority value depends on scheduling policy. Valid values fall within one of the following ranges: o PRI_OTHER_MIN <= priority <= PRI_OTHER_MAX o PRI_FIFO_MIN <= priority <= PRI_FIFO_MAX o PRI_RR_MIN <= priority <= PRI_RR_MAX o PRI_FG_MIN_NP <= priority <= PRI_FG_MAX_NP o PRI_BG_MIN_NP <= priority <= PRI_BG_MAX_NP If you create a new thread without specifying a threads attributes object that contains a changed priority attribute, the default priority of the newly created thread is the midpoint between PRI_OTHER_MIN and PRI_OTHER_MAX (the midpoint between the minimum and the maximum for the SCHED_OTHER policy). When you call this routine to specify a minimum or maximum priority, use the appropriate symbol; for example, PRI_FIFO_MIN or PRI_FIFO_MAX. To specify a value between the minimum and maximum, use an appropriate arithmetic expression. For example, to specify a priority midway between the minimum and maximum for the Round Robin scheduling policy, specify the following concept using your programming language's syntax: pri_rr_mid = (PRI_RR_MIN + PRI_RR_MAX)/2 If your expression results in a value outside the range of minimum to maximum, an error results when you use it. DESCRIPTION The pthread_setprio() routine changes the current priority of a thread. A thread can change its own priority using the identifier returned by pthread_self(). Changing the priority of a thread can cause it to start executing or be preempted by another thread. The effect of setting different priority values depends on the scheduling priority assigned to the thread. The initial scheduling priority is set by calling the pthread_attr_setprio() routine. Note that pthread_attr_setprio() sets the priority attribute that is used to establish the priority of a new thread when it is created. How- ever, pthread_setprio() changes the priority of an existing thread. RETURN VALUES If successful, this routine returns the previous priority. If the function fails, errno may be set to one of the following values: Return Error Description ___________________________________________________________ Previous priority Successful completion. -1 [EINVAL] The value specified by thread is invalid. -1 [ENOTSUP] An attempt is made to set the policy to an unsupported value. -1 [ESRCH] The value specified by thread does not refer to an existing thread. -1 [EPERM] The caller does not have the appropriate privileges to set the priority of the specified thread. RELATED INFORMATION FUNCTIONS: pthread_attr_setprio pthread_attr_setsched pthread_create pthread_self pthread_setscheduler 4 pthread_setscheduler NAME pthread_setscheduler - Changes the current scheduling policy and priority of a thread SYNOPSIS #include int pthread_setscheduler( pthread_t thread, int scheduler, int priority ); PARAMETERS thread Thread whose scheduling policy is to be changed. scheduler New scheduling policy value for the thread specified in thread. Valid values are as follows: SCHED_FIFO (First In, First Out) The highest-priority thread runs until it blocks. If there is more than one thread with the same priority, and that priority is the highest among other threads, the first thread to begin running continues until it blocks. SCHED_RR (Round Robin) The highest-priority thread runs until it blocks; however, threads of equal priority, if that priority is the highest among other threads, are timesliced. Timeslicing is a process in which threads alternate using available processors. SCHED_OTHER (Default) All threads are timesliced. SCHED_OTHER ensures that all threads, regardless of priority, receive some scheduling, and thus no thread is completely denied execution time. (However, SCHED_OTHER threads can be denied execution time by SCHED_FIFO or SCHED_RR threads.) SCHED_FG_NP (Foreground) Same as SCHED_OTHER. Threads are timesliced and priorities can be modified dynamically by the scheduler to ensure fairness. SCHED_BG_NP (Background) Like SCHED_OTHER, ensures that all threads, regardless of priority, receive some scheduling. However, SCHED_BG_NP can be denied execution by any of the other scheduling policies. priority New priority value of the thread specified in thread. The priority attribute depends on scheduling policy. Valid values fall within one of the following ranges: o PRI_OTHER_MIN <= priority <= PRI_OTHER_MAX o PRI_FIFO_MIN <= priority <= PRI_FIFO_MAX o PRI_RR_MIN <= priority <= PRI_RR_MAX o PRI_FG_MIN_NP <= priority <= PRI_FG_MAX_NP o PRI_BG_MIN_NP <= priority <= PRI_BG_MAX_NP If you create a new thread without specifying a threads attributes object that contains a changed priority attribute, the default priority of the newly created thread is the midpoint between PRI_OTHER_MIN and PRI_OTHER_MAX (the midpoint between the minimum and the maximum for the SCHED_OTHER policy). When you call this routine to specify a minimum or maximum priority, use the appropriate symbol; for example, PRI_FIFO_MIN or PRI_FIFO_MAX. To specify a value between the minimum and maximum, use an appropriate arithmetic expression. For example, to specify a priority midway between the minimum and maximum for the Round Robin scheduling policy, specify the following concept using your programming language's syntax: pri_rr_mid = (PRI_RR_MIN + PRI_RR_MAX)/2 If your expression results in a value outside the range of minimum to maximum, an error results when you use it. DESCRIPTION The pthread_setscheduler() routine changes the current scheduling policy and priority of a thread. Call this routine to change both the priority and scheduling policy of a thread at the same time. To change only the priority, call the pthread_setprio() routine. A thread changes its own scheduling policy and priority by using the identifier returned by pthread_self(). Changing the scheduling policy or priority, or both, of a thread can cause it to start executing or to be preempted by another thread. This routine differs from pthread_attr_setprio() and pthread_attr_setsched() because those routines set the priority and scheduling policy attributes that are used to establish the priority and scheduling policy of a new thread when it is created. This routine, how- ever, changes the priority and scheduling policy of an existing thread. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description ______________________________________________________________ 0 Successful completion. -1 [EINVAL] The value specified by thread is invalid. -1 [ENOTSUP] An attempt is made to set the policy to an unsupported value. -1 [ESRCH] The value specified by thread does not refer to an existing thread. -1 [EPERM] The caller does not have the appropriate privileges to set the priority of the specified thread. RELATED INFORMATION FUNCTIONS: pthread_attr_setprio pthread_attr_setsched pthread_create pthread_self pthread_setprio 4 pthread_setspecific NAME pthread_setspecific - Sets the thread-specific data associated with the specified key for the current thread SYNOPSIS #include int pthread_setspecific( pthread_key_t key, pthread_addr_t value ); PARAMETERS key Context key value that uniquely identifies the context value specified in value. This key value must have been obtained from pthread_keycreate(). value Address containing data to be associated with the specified key for the current thread; this is the thread-specific data. DESCRIPTION The pthread_setspecific() routine sets the thread-specific data associ- ated with the specified key for the current thread. If a value has already been defined for the key in this thread, the new value is sub- stituted for it. Different threads can bind different values to the same key. These values are typically pointers to blocks of dynamically allocated memory that are reserved for use by the calling thread. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description _____________________________________________ 0 Successful completion. -1 [EINVAL] The key value is invalid. RELATED INFORMATION FUNCTIONS: pthread_getspecific pthread_keycreate 4 pthread_signal_to_cancel_np NAME pthread_signal_to_cancel_np - Cancels the specified thread SYNOPSIS #include int pthread_signal_to_cancel_np( sigset_t *sigset, pthread_t *thread ); PARAMETERS sigset Signal mask containing a list of signals that, when received by the process, cancels the specified thread. thread Thread canceled if a valid signal is received by the process. DESCRIPTION The pthread_signal_to_cancel_np() routine requests that the specified thread be canceled if one of the signals specified in the signal mask is received by the process. The set of legal signals is the same as that for the sigwait() service. The sigset parameter is not validated. If it is invalid, this routine will return successfully but neither the speci- fied thread nor the previously specified thread will be canceled if a signal occurs. Note that the address of the specified thread is saved in a per-process global variable. Therefore, any subsequent call to this routine by your application or any library function will supercede the thread specified in the previous call, and that thread will not be canceled if one of the signals specified for it is delivered to the process. In other words, take care when you call this routine; if another thread calls it after you do, the expected result of this routine will not occur. RETURN VALUES If the function fails, errno may be set to one of the following values: Return Error Description _____________________________________________________________ 0 Successful completion. -1 [EINVAL] The value specified by thread is invalid. RELATED INFORMATION FUNCTIONS: pthread_cancel 4 pthread_testcancel NAME pthread_testcancel - Requests delivery of a pending cancel to the current thread SYNOPSIS #include void pthread_testcancel(); DESCRIPTION The pthread_testcancel() routine requests delivery of a pending cancel to the current thread. The cancel is delivered only if a cancel is pending for the current thread and general cancel delivery is not currently disabled. (A thread disables delivery of cancels to itself by calling the pthread_setcancel() routine.) This routine, when called within very long loops, ensures that a pending cancel is noticed within a reasonable amount of time. RETURN VALUES No value is returned. RELATED INFORMATION FUNCTIONS: pthread_cancel pthread_setasynccancel pthread_setcancel 4 pthread_unlock_global_np NAME pthread_unlock_global_np - Unlocks a global mutex SYNOPSIS #include void pthread_unlock_global_np(); DESCRIPTION The pthread_unlock_global_np() routine unlocks the global mutex when each call to pthread_lock_global_np() is matched by a call to this rou- tine. For example, if you called pthread_lock_global_np() three times, pthread_unlock_global_np() unlocks the global mutex when you call it the third time. If no threads are waiting for the global mutex, it becomes unlocked with no current owner. If one or more threads are waiting to lock the global mutex, one thread returns from its call to pthread_lock_global_np(). The scheduling policy is used to determine which thread acquires the global mutex. For the policies SCHED_FIFO and SCHED_RR, a blocked thread is chosen in priority order. The results of calling this routine are unpredictable if the global mutex is already unlocked. The results of calling this routine are also unpredictable if the global mutex is owned by a thread other than the calling thread. This routine is not portable. RETURN VALUES No value is returned. RELATED INFORMATION FUNCTIONS: pthread_lock_global_np pthread_mutexattr_setkind_np pthread_mutex_lock pthread_mutex_unlock 4 pthread_yield NAME pthread_yield - Notifies the scheduler that the current thread is willing to release its processor SYNOPSIS #include void pthread_yield(); DESCRIPTION The pthread_yield() routine notifies the scheduler that the current thread is willing to release its processor to other threads of the same priority. (A thread releases its processor to a thread of a higher priority without calling this routine.) If the current thread's scheduling policy (as specified in a call to the pthread_attr_setsched() or pthread_setscheduler() routine) is SCHED_FIFO or SCHED_RR, this routine yields the processor to other threads of the same or a higher priority. If no threads of the same priority are ready to execute, the thread continues. This routine allows knowledge of the details of an application to be used to increase fairness. It increases fairness of access to the pro- cessor by removing the current thread from the processor. It also increases fairness of access to shared resources by removing the current thread from the processor as soon as it is finished with the resource. Call this routine when a thread is executing code that denies access to other threads on a uniprocessor if the scheduling policy is SCHED_FIFO. Use pthread_yield() carefully because misuse causes unnecessary context switching, which increases overhead without increasing fairness. For example, it is counterproductive for a thread to yield while it has a needed resource locked. RETURN VALUES No value is returned. RELATED INFORMATION FUNCTIONS: pthread_attr_setsched pthread_setscheduler 4 sigwait NAME sigwait - Causes a thread to wait for an asynchronous signal SYNOPSIS #include int sigwait( sigset_t *set ); PARAMETERS set Set of asynchronous pending signals from which this routine chooses one signal on which the calling thread will wait. DESCRIPTION This routine causes a thread to wait for an asynchronous signal by choosing a pending signal from set, atomically clearing it from the system's set of pending signals and returning that signal number. If no signal in set is pending at the time of the call, the thread is blocked until one or more signals becomes pending. The signals defined by set may be unblocked during the call to this routine and will be blocked when the thread returns from the call unless some other thread is currently waiting for one of those signals. If more than one thread is using this routine to wait for the same signal, only one of these threads will return from this routine with the signal number. RETURN VALUES Possible return values are as follows: Return Error Description __________________________________________________ Signal number Successful completion. -1 [EINVAL] The value specified by set is invalid. RELATED INFORMATION FUNCTIONS: pthread_cancel pthread_setasynccancel 2 DCE_SECURITY DCE Security Services provide authentication and authorization within a cell and is based upon MIT's Kerberos private key encryption system. 3 Admin_Intro NAME sec_intro - Introduction to the DCE Security administrative commands DESCRIPTION This section describes DCE Security commands for system administration. These commands are: acl_edit Manages Access Control Lists (ACLs) for DCE objects auditd Starts the DCE Audit Daemon chpass Changes user information, such as login name, password, home directory, password and account expiration dates,and login shell. The implementation of this utility is platform- specific. Use the chpass utility supplied your platform vendor for changing user information. dce_login Validates a principal's identity and obtains a principal's network credentials. This command is used primarily during DCE configuration. Use the login utility supplied by your platform vendor for user login. kdestroy Destroys your login context and credentials kinit Obtains and caches a ticket granting ticket klist Lists cached tickets passwd_export Updates local password and group files from DCE registry data passwd_import Creates DCE registry entries based on password and group file entries passwd_override Establishes DCE registry overrides for a principal on a local node pwd_strengthd Sample password management server rgy_edit Edits the registry database sec_admin Administers the Security Server sec_create_db Creates registry databases secd The Security Server daemon sec_salvage_db Reconstructs or recovers a registry database See the command's reference page for further information on each command. 4 acl_edit NAME acl_edit - Edits or lists an object's ACLs SYNOPSIS acl_edit {[-e] pathname | -addr string_binding component_name} [-ic | -io] [-n | -c] [command_line_subcommands] [-ngui] [-v] OPTIONS -e pathname Specifies that the ACL on the Directory Service entry is to be edited. You must specify the pathname argument if you use the -e option. The -e option is especially useful in case of an ambiguous pathname. The pathname argument can be interpreted in two ways if it is the name of a leaf object in the Directory Service (that is, if it is not the name of a directory). It can be interpreted as the Directory Service entry itself, or as the object (whatever it is) referenced by that Directory Service entry. When such a path- name is specified, the -e option directs acl_edit to the ACL on the Directory Service entry. -addr string_binding component_name The -addr option lets you identify the object whose ACLs you want to edit by supplying the RPC binding handle of the ACL Manager that controls access to the object (with the string_binding argument) and the relative pathname of the object (with the component_name argument). Because you have identified the RPC binding handle, you can specify only the object's relative pathname for component_name. The most common way to identify the object whose ACLs you want to manipulate is through the pathname argument,described below. The -addr option is used primarily by applications that do not use the Directory Service, but do use the generic ACL Manager. It can also be used if the Directory Service is unavailable. -ic For container objects only, specifies that the object's Initial Container Creation ACL is to be edited. The Initial Container Creation ACL is applied by default to any containers created within the ACL'd container. If this option is specified and the object named in pathname is not a container, an error is returned. -io For container objects only, specifies that the object's Initial Object Creation ACL is to be edited. The Initial Object Creation ACL is applied by default to any simple objects (that is, objects that are not containers) created within the ACL'd container. If this option is specified and the object is not a container, an error is returned. -n Specifies that a new mask should not be calculated. This option is useful only for objects that support the mask_obj entry type and that are required to recalculate a new mask after they are modified. If a modify operation creates a mask that unintentionally adds permissions to an existing acl entry, the modify causing the mask recalculation will abort with an error unless you specify either the -c or -n option. -c Creates or modifies the object's mask_obj type entry with permissions equal to the union of all entries other than type user_obj, other_obj, and unauthenticated. This creation or modification is done after all other modifications to the ACL are performed. The new mask is set even if it grants permissions previously masked out. It is recommended that you use this option only if not specifying it results in an error. This option is useful only for objects that support the mask_obj entry type and are required to recalculate a new mask after they are modified. If a modify operation creates a mask that unintentionally adds permissions to an existing acl entry, the modify causing the mask recalculation will abort with an error unless you specify either the -c or -n option. If you specify the -c option for an ACL that does not support mask_obj entry type, acl_edit returns an error when it attempts to save the ACL, aborting all subcommands supplied on the command line. -ngui Specifies that a Graphical User Interface (GUI) should not be used even if a GUI is available. If your version of acl_edit supports a GUI and your terminal is capable of using it, invoking acl_edit without this option will bring up the GUI mode. Use the -ngui option to bring up command- line mode. However, if a GUI is not available, or the terminal is not capable of using the GUI, acl_edit comes up in command-line mode regardles of wheter you supply this option or not. -v Run in verbose mode. ARGUMENTS pathname The full pathname of the object whose ACL is to be viewed or edited. If the object is in another cell, pathname must be fully qualified to include the cell identifier. command_line_subcommands The command-line subcommands, which act on the object specified by pathname, are entered as part of the command string that invokes acl_edit. Only one command-line subcommand can be specified per invocation. The commands follow. See the description of the equivalent interactive subcommand for a more detailed description of the command functions. -m [acl_entry] acl_entry... Adds a new ACL entry or changes the permissions of an existing entry. You can enter multiple entries, each separated by a space. -p Purges all masked permissions (before any other modifications are made). This option is useful only for ACLs that contain an entry of type mask_obj. Use it to prevent unintentionally granting permissions to an existing entry when a new mask is calculated as a result of adding or modifying an ACL entry. -d [acl_entry] acl_entry... Deletes an existing entry from the ACL associated with the specified object. You can enter multiple entries, each separated by a space. -s [acl_entry] acl_entry... Replaces (substitutes) the ACL information associated with this object with acl_entry. All existing entries are removed and replaced by the newly specified entries. If you specify the -s subcommand, you cannot specify the -f or -k subcommand. You can enter multiple entries, each separated by a space. -f file Assigns the ACL information contained in file to the object. All existing entries are removed and replaced by the entries in the file. If you specify the -f sub- command, you cannot specify the -s or -k subcommand. -k Removes all entries, except entries of type user_obj (if they are present). If you specify the -k subcommand, you cannot specify the -f or -s subcommand. -l Lists the entries in the object's ACL. The command-line subcommands are evaluated in the following order: 1. -p 2. -s or -f or -k 3. -d 4. -m 5. -l NOTES With the exception of the following subcommands, this command is replaced at Revision 1.1 by the dcecp command. This command may be fully replaced by the dcecp command in a future release of DCE, and may no longer be supported at that time. + abort + commit + exit + help + test access DESCRIPTION The acl_edit command is a client program that, when invoked, binds to the specified object's ACL Manager (which is implemented in the object's server), and allows the user to manipulate the object's ACL through the standard DCE ACL interface. This interface is the sec_acl_...() interface documented in the OSF DCE Application Development Reference. The acl_edit command automatically binds to the server of the object specified, and then communicates (through the standard DCE ACL interface) with that server's ACL manager in response to user input. Exactly what the object "specified" is depends partly on whether or not the -e option is specified. Specifying -e means that you want to operate on the Directory Service ACL - in other words, you want acl_edit to bind to the CDS server and allow you to operate on the ACL maintained by that server on the object's directory entry. If, on the the ACL on the object to which the directory entry refers - then you simply omit the -e option. The result will be that acl_edit will bind to that object's server (the server must, of course, implement an ACL manager), giving you access to the object's ACL. All acl_edit subcommands act on the object specified by pathname when you invoked acl_edit. You can invoke acl_edit in either command-line or interactive mode: + To invoke acl_edit in command-line mode, enter the command, the object's pathname, options, and the command-line subcommand on th line that invokes acl_edit. Only one command-line subcommand can be entered per acl_edit invocation. + To invoke acl_edit in interactive mode, enter only acl_edit, the object's pathname, and options. The acl_edit prompt is then displayed. In this mode, you enter interactive subcommands that let you edit and view entries in the object's ACL and view help information about the acl_edit command itself. Changes you make in command-line mode are saved when you enter the command. In interactive mode, you must explicitly save your changes. To do so, use the commit subcommand to save the changes without exiting acl_edit or the exit subcommand to save the changes and exit acl_edit. Use the abort subcommand to exit acl_edit and save none of the changes you have made. When you invoke acl_edit for a specific object's ACL, that ACL is not locked. This means that it is possible for multiple users to edit the ACL simultaneously, with each change overwriting the previous changes. For this reason, the number of users assigned rights to change a particular ACL should be tightly controlled and limited to one user if possible. INTERACTIVE SUBCOMMANDS The following subcommands are available when acl_edit is invoked in interactive mode. All of the commands act on the ACL associated with the object specified by pathname when acl_edit was invoked. ? Displays the available acl_edit subcommands. ab[ort] Exits acl_edit without saving the changes to the object's ACL. as[sign] filename Applies the ACL entries in filename to the specified object. This subcommand removes existing entries and replaces them with the entries in the file. c[ell] name Sets the cell name to be associated with the ACL. This sub- command is used primarily to facilitate copying ACLs to different cells. The default cell name stays in place until you run the subcommand again to change it. co[mmit] Saves all changes to the ACL without exiting. d[elete] acl_entry Deletes the specified ACL entry. e[xit] Exits from acl_edit, saving any changes to the object's ACL. g[et_access] Displays the permissions granted in the specified object's ACL to the principal that invoked acl_edit. h[elp] [command ...] Initiates the help facility. If you enter only the command help, acl_edit displays a list of all commands and their functions. If you enter help and a command (or commands separated by a space), acl_edit displays help information on the specified commands. Entering help sec_acl_entry displays information about ACL entries. k[ill_entries] Removes all ACL entries except the user_obj entry if it exists. l[ist] Lists the entries in the object's ACL. m[odify] acl_entry [-n | -c] Adds a new ACL entry or replaces an existing ACL entry. This command affects a single ACL entry. To add or replace all of an object's ACL entries, see the su[bstitute] subcommand. For objects that support the mask_obj entry type and are required to calculate a new mask when their ACLs are modified, the -n option specifies that a new mask should not be calculated; the -c option specifies that the object's mask_obj entry should have permissions equal to the union of all entries other than user_obj, other_obj, and unauthenticated. The mask is calculated after the ACL is modified. If you use the -c option, the new mask is set even if it grants permissions previously masked out. It is recommended that you use the -c option only if not specifying it results in an error. If the new mask unintentionally grants permissions to an existing entry, the modify operation causing the mask recalculation will abort with an error unless you specify either the -c or -n option. p[ermissions] Lists the available permission tokens and explanations. pu[rge] Purges all masked permissions. This option is useful only for ACLs that contain an entry of type mask_obj. Use it to prevent unintentionally granting permissions to an existing entry when a new mask is calculated as a result of adding or modifying an ACL entry. su[bstitute] acl_entry [acl_entry ...] Replaces all ACL entries with the one or ones specified. This subcommand removes all existing entries and adds the ones specified by acl_entry. To replace only a single ACL entry, see the m[odify] subcommand. t[est_access] [permissions ...] Tests whether or not the permissions specified in the command are granted to the principal under whose DCE identity the acl_edit command was invoked. The option returns Granted if the permissions are granted or Denied if they are not. ACL ENTRIES An ACL entry has the following syntax: type[:key]:permissions where: type Identifies the role of the ACL entry. key Identifies the specific principal or group to whom the entry applies. For an entry type of extended, key contains the ACL data. permissions The ACL permissions. A thorough description of each syntax component follows. Type The type tag identifies the role of the ACL entry. Valid types are the following: + user_obj - Permissions for the object's real or effective user. + group_obj - Permissions for the object's real or effective group. + other_obj - Permissions for others in the local cell who are not otherwise named by a more specific entry type. + user - Permissions for a specific principal user in the ACL's cell. This type of ACL entry must include a key that identifies the specific principal. + group - Permissions for a specific group in the ACL's cell. This type of ACL entry must include a key that identifies the specific group. + foreign_user Permissions for a specific, authenticated user in a foreign cell. This type of ACL entry must include a key that identifies the specific principal and the principal's cell. + foreign_group Permissions for a specific, authenticated group in a foreign cell. This type of ACL entry must include a key that identifies the specific group and the group's cell. + foreign_other Permissions for all authenticated principals in a specific foreign cell, unless those principals are specifically named in an ACL entry of type foreign_user or members in a group named in an entry of type foreign_group. This type of ACL entry must include a key that identifies the specific foreign cell. + any_other - Permissions for all authenticated principals unless those principals match a more specific entry in the ACL. + mask_obj - Permissions for the object mask that is applied to all entry types except user_obj, other_obj, and unauthenticated. + unauthenticated Maximum permissions applied when the accessor does not pass authentication procedures. This entry is used for principals that have failed authentica- tion due to bad keys, principals who are entirely outside of any authentication cell, and principals who choose not to use authenticated access. Permissions granted to an unauthenticated principal are masked with this entry, if it exists. If this entry does not exist, access to unauthenticated principals is always denied. + extended - A special entry that allows client applications running at earlier DCE versions to copy ACLs to and from ACL Managers running at the current DCE version without losing any data. The extended entry allows the application running at the lower version to obtain a printable form of the ACL. The extended ACL entry has the following form: extended:uuid.ndr.ndr.ndr.ndr.number_of_byte.data where: uuid Identifies the type extended ACL entry. (This UUID can identify one of the ACL entry types described here or an as-yet- undefined ACL entry type.) ndr.ndr.ndr.ndr Up to three Network Data Representation (NDR) format labels (in hexadecimal format and separated by periods) that identify the encoding of data. number_of_bytes A decimal number that specifies the total number of bytes in data. data The ACL data in hexadecimal form. (Each byte of ACL data is two hexadecimal digits.) The ACL data includes all of the ACL entry specifications except the permissions (described later) that are entered separately. The data is not interpreted; it is assumed that the ACL Manager to which the data is being passed can understand that data. Key The key identifier (principal or group name) specifies the principal or group to which the ACL entry applies. For entries of entry type extended, key is the data passed from one ACL Manager to another. A key is required for the following types of ACL entries: + user - Requires a principal name only. + group - Requires a group name only. + foreign_user - Requires a fully qualified cell name in addition to the principal name. + foreign_group - Requires a fully qualified cell name in addition to the group name. + foreign_other - Requires a fully qualified cell name. Permissions The permissions argument specifies the set of permissions that defines the access rights conferred by the entry. Since each ACL Manager defines the permission tokens and meanings appropriate for the objects it controls, the actual tokens and their meanings vary. For example, the Distributed File Service, the Directory Service, and the Security Registry Service each implemhent a separate ACL Manager, and each can use a different set of tokens and permissions. This means that file system objects, objects in the namespace, and registry objects could each use different permissions. Use the p[ermissions] subcommand to display the currently available tokens and their meanings. See the documentation for the DCE component you are using to obtain a more detailed description of its specific permissions. EXAMPLES 1. The following example uses the interactive interface to set permis- sions for the unauthenticated and mask_obj entry type: sec_acl_edit> m mask_obj:rwx sec_acl_edit> m unauthenticated:r 2. The following example uses the interactive interface to set permis- sions for the effective user, group, and others in the ACL's cell: sec_acl_edit> m user_obj:crwx sec_acl_edit> m group_obj:rwx sec_acl_edit> m other_obj:rwx 3. The following example uses the command-line interface to invoke acl_edit and assign permissions for the file progress_chart to the authenticated user mike in the local cell: % acl_edit /.../dresden.com/fs/walden/progress_chart -m user:mike:cx Note that because this entry will be filtered through the object mask (mask_obj), which specifies only rwx permissions, the actual permissions will be rwx, not crwx. The l(ist) subcommand will show those permissions as follows: user:mike:crwx #effective -rwx--- 4. The following example uses the interactive interface to set permis- sions for the authenticated foreign user named burati in the cell named /.../usc-cs.uscal.edu: sec_acl_edit> m foreign_user:/.../usc-cs.uscal.edu/sailing/staff/bux 5. The following example uses the non-interactive command-line inter- face to invoke and set the Initial Container Creation permissions for the directory that is named walden: % acl_edit /.../dresden.com/fs/walden -ic -m /user:walden:crwxid 4 chpass NAME chpass - Changes user database information SYNOPSIS chpass [user] OPTIONS None ARGUMENTS user The user argument indicates the user whose database informa- tion you want to change. If omitted, you are prompted for the user. DESCRIPTION The chpass command changes user database information associated with user. Note that the functionality of the chpass command as described in this reference page can change depending on the platform on which you are running the command. Each platform vendor integrates this command (based on 4.4BSD source) with the vendor's own login facility. You can edit information associated with user only if you are user or have the appropriate rights. chpass prompts for the information it needs. The information will include all or a subset of the following list: o Login - The login name used to access the account. Because the login name controls file access, they must be unique within the cell. In multicell environments, this uniqueness is ensured by automatically appending the cell designator to the user's name. While it is possible to have multiple entries with identical login names, it is usually a mistake to do so. Routines that manipulate these files will often return only one of the multiple entries, and that one by random selection. o Password - The encrypted account password. Once the information has been verified, the network registry is updated. RELATED INFORMATION COMMANDS: login dce_login 4 dce_login NAME dce_login - Validates a principal's identity and obtains the principal's network credentials SYNOPSIS dce_login [principal_name] [password] [-c] [-e[xec] cmd_string] OPTIONS -c Causes the principal's identity to be certified. If you do not specify -c, the principal's identity is validated only. [-e[xec] cmd_string] Executes the command supplied as cmd_string. ARGUMENTS principal_name The name of the principal to log in as. password The password for principal_name. DESCRIPTION The dce_login command is supplied for use in DCE configuration. It vali- dates a principal's identity and obtains the principal's network creden- tials. If the -c option is supplied, the command also certifies the principal's identity, and, if the principal is able to be certified, creates an entry for the principal in the machine's local registry. If the principal is not able to be certified, the command attempts to log the principal in via the local registry. The -exec option executes the command specified by cmd_string after login. If cmd_string is specified without a full pathname, the path prefix is obtained by searching the directories according to the PATH variable. The principal_name argument specifies the name of the principal who is logging in. The password argument specifies the principal's password. If you do not supply a principal name or a principal password, dce_login prompts for them. If you enter them both on the command line, you must specify the principal name first, followed by the password. The dce_login command executes the shell specified in the SHELL environ- ment variable. Note that if the clocks on the Security server and client machines are not synchronized to within 2 or 3 minutes of each other, you may receive a password validation error and be unable to be validated. 4 kdestroy NAME kdestroy - Destroys a principal's login context and associated credentials SYNOPSIS kdestroy [-c cache_name] OPTIONS -c cache_name Specifies that the login context and associated credentials for cache_name should be destroyed instead of the default cache. DESCRIPTION The kdestroy command destroys a principal's login context and the principal's credentials. Until the credentials are reestablished by either executing the dce_login command or the kinit command, the principal and any processes created by the principal will be limited to unauthenticated access. FILES dce$local:[var.security.creds]DCECRED* If the KRB5CCNAME logical name is set, the default credentials cache. RELATED INFORMATION COMMANDS: klist kinit 4 kinit NAME kinit - Obtains and caches ticket-granting ticket SYNOPSIS kinit [-c cachename] [-f] [-l lifetime] [-p] [-r lifetime] [-v] [principal] OPTIONS -c cachename Specifies an alternative credentials cache, cachename, to be used in place of the default credentials cache. The kinit command overwrites the contents of the alternative cache with the current credentials. The name of the default credentials cache may vary between systems. However, if the KRB5CCNAME logical name is set, its value is used to name the default cache. -f Requests the FORWARDABLE option. This option allows a ticket- granting ticket with a different network address than the present ticket-granting ticket to be issued to the principal. For forwardable tickets to be granted, the principal's account in the registry must specify that the principal can be granted forwardable tickets. -l lifetime Specifies the lifetime of the ticket-granting ticket in hours. If this option is not specified, the default ticket lifetime (set by each site using the rgy_edit command) is used. -p Requests the PROXIABLE option. This option allows a ticket with a different network address than the present ticket to be issued to the principal. For proxiable tickets to be granted, the principal's account in the registry must specify that the principal can be granted proxiable tickets. -r lifetime Requests the RENEWABLE option. This option allows the tickets issued to the principal to be renewed. For renewable tickets to be granted, the principal's account in the registry must specify that the principal can be granted renewable tickets. The lifetime of the ticket-granting ticket is specified in hours by lifetime. -v Specifies that the command should run in verbose mode. ARGUMENTS principal The principal argument specifies the name of the principal for whom the ticket-granting ticket should be obtained. If principal is omitted, the principal name from the existing cache is reused. DESCRIPTION The kinit command can be used to refresh a DCE credentials cache. When you invoke kinit, it prompts for your password. The ticket lifetime and renewable lifetime are set in the following format: {num {interval}}... where: num A number that specifies the number of the interval; interval can be specified by the following: + w - weeks + d - days + h - hours + m - minutes + s - seconds For example, to set the lifetime to 3 weeks, 5 days, and 10 hours, the entry would be the following: 3w5d10h FILES dce$local:[var.security.creds]DCECRED* If the KRB5CCNAME logical name is not set, the name of the file is in the form shown. If the KRB5CCNAME logical name is set, its setting determines the name of the file. RELATED INFORMATION COMMANDS: klist kdestroy 4 klist NAME klist - Lists cached tickets SYNOPSIS klist [-c cachename] [-e] [-f] OPTIONS -c cachename Specifies that the contents of the cache identified by cachename should be displayed instead of the contents of the default cache. -e Includes expired tickets in the display. Without this option, only current tickets are displayed. -f Displays option settings on the tickets. The options are + D (postdatable) + d (postdated) F (forwardable) + f (forwarded) + I (initial) + i (invalid) + P (proxiable) + p (proxy) + R (renewable) DESCRIPTION The klist command lists the primary principal and tickets held in the default credentials cache, or in the cache identified by cachename if the -c option is used. The name of the default credentials cache can vary between systems. How- ever, if the KRB5CCNAME logical name is set, its value is used to name the default cache. If it is not set, the form of the name is dce$local:[var.security.creds]DCECRED*. RELATED INFORMATION COMMANDS: kinit kdestroy krb5 4 DCE$EXPORT The DCE EXPORT utility allows you to create an OpenVMS authorization file from an existing DCE registry. The DCE registry entries (or a subset of the registry entries) are converted into records in the OpenVMS SYSUAF file and rights database. Conversions are essentially a reversal of those made with the IMPORT function. Passwords cannot be exported. Instead, the automatic synchronization feature that occurs during integrated login is used to export user pass- words. The DCE EXPORT utility also creates and maintains an exclude list. The exclude list contains the DCE names of users who do not have, and do not require, an OpenVMS account. This feature allows DCE EXPORT to skip over these users during EXPORT operations. NOTE: The DCE EXPORT utility described in this section cannot be satisfied by the export function shipped with OSF DCE because of substantial differences between OpenVMS and UNIX user registry data. 5 File_Info The DCE EXPORT utility is shipped as an OpenVMS executable image named DCE$EXPORT.EXE. The image resides in the SYS$SYSTEM directory. The DCE EXPORT exclude file is named by default DCE$EXPORT_EXCLUDE.DAT and also resides in SYS$SYSTEM. You can change the name or location, or both, of this file by defining the logical name DCE$EXPORT_EXCLUDE to point to the new filename and location. 5 Running_EXPORT The DCE EXPORT utility allows system administrators to create an OpenVMS authorization file from an existing DCE registry. Integrated Login provides two methods of running the DCE EXPORT utility, as follows. o By invoking the DCE EXPORT utility using a predefined symbol. $ EXPORT EXPORT> You can also specify a single DCE EXPORT command on the command line. Control returns to DCL after the command is executed. $ EXPORT command $ SYS$COMMON:[SYSMGR]DCE$DEFINE_REQUIRED_COMMANDS.COM defines the DCE symbol EXPORT, which is used to invoke the DCE EXPORT utility. If this symbol is not defined in your environment, you can define the symbol as follows: $ EXPORT :== $SYS$SYSTEM:DCE$EXPORT o By issuing the RUN command. $ RUN SYS$SYSTEM:DCE$EXPORT EXPORT> See the HP DCE for OpenVMS Alpha and OpenVMS I64 Reference Guide for detailed descriptions of the EXPORT commands. 5 Messages 6 EXP_ACCEXISTS OpenVMS account for already exists Explanation: Could not export because it has already been exported. User Action: None. 6 EXP_ADDDCEACC account for successfully added to OpenVMS Explanation: An OpenVMS acount was successfully created for . User Action: Note directly preceding and following messages for warnings. 6 EXP_ADDDCEUAF principal successfully added to DCE$UAF Explanation: Principal successfully added to the DCE$UAF file as part of the EXPORT operation. Message displayed only if /INFORM is specified on the EXPORT command line. User Action: None. 6 EXP_ADDUAF principal successfully exported to OpenVMS Explanation: An OpenVMS account for successfully created for DCE . User Action: Note directly preceding and following messages for warnings. 6 EXP_BINDERR error binding to DCE security registry Explanation: Cannot connect to the DCE security server. User Action: Note accompanying error message for more details. 6 EXP_CREDCEUAF created new DCE$UAF file Explanation: A new DCE$UAF file was created. User Action: None. 6 EXP_DCEERR Explanation: Accompanying DCE error message. User Action: Use this message to solve the problem generating the error. 6 EXP_DCELOGIN error in DCE login Explanation: Could not perform a DCE login. User Action: Enter valid DCE principal and password combination. 6 EXP_DCEUAFERR error searching DCE$UAF Explanation: Error searching or reading DCE$UAF file. User Action: Note accompanying error message for more details. 6 EXP_DELDCEUAF principal successfully deleted from DCE$UAF Explanation: Principal successfully deleted from DCE$UAF as part of larger delete operation. Message is displayed only if /INFORM is specified on the EXPORT command line. User Action: None. 6 EXP_DISUSER remains DISUSER-ed Explanation: OpenVMS account for was successfully created but could not enable the account. User Action: Manually remove the DISUSER flag using the AUTHORIZE utility. 6 EXP_ERRACCEXC error accessing DCE EXPORT exclude file Explanation: Could not access DCE EXPORT exclude file. User Action: Note accompanying error message for more details. 6 EXP_ERRADDEXC error adding principal to DCE EXPORT exclude file Explanation: Could not add principal to DCE EXPORT exclude file. User Action: Note accompanying error message for more details. 6 EXP_ERRADDUAF error adding principal to DCE$UAF file Explanation: Could not add principal name to DCE$UAF file. User Action: Note accompanying error message for more details. 6 EXP_ERRCRACC error creating OpenVMS account for Explanation: Could not create an OpenVMS account for . User Action: See accompanying error message for more details. 6 EXP_ERRCRDCEUAF error creating DCE authorization file Explanation: An error occurred while attempting to create the DCE$UAF file. User Action: See accompanying message for details. 6 EXP_ERRCREUAF error creating OpenVMS account for - see following messages Explanation: Could not create the OpenVMS account for . User Action: Note accompanying error messages for more details. 6 EXP_ERRDCEUAF error accessing DCE authorization file Explanation: An error occurred while attempting to access the DCE$UAF file. User Action: See accompanying message for details. 6 EXP_ERRDELEXC error deleting principal from DCE EXPORT exclude file Explanation: Could not delete principal from DCE EXPORT exclude file. User Action: Note accompanying error message for more details. 6 EXP_ERRDELUAF error deleting principal from DCE$UAF file Explanation: Could not delete principal from DCE$UAF file. User Action: Note accompanying error message for more details. 6 EXP_ERRENAUSR error enabling user Explanation: Could not remove DISUSER flag from 's account. User Action: Manually remove the flag using the AUTHORIZE utility. 6 EXP_ERRQUOTA error assigning disk quota to username - see following messages Explanation: Error(s) occurred while attempting to set up disk quota for User Action: Note the messages following this message. 6 EXP_ERRSETPW error setting password for Explanation: Could not set password for OpenVMS . User Action: Manually set password using the AUTHORIZE utility. 6 EXP_ERRSPAWN error spawning subprocess Explanation: Error spawning subprocess with the SPAWN command. User Action: Check user runtime configuration. Refer to appropriate OpenVMS documentation for more details. 6 EXP_ERRSYSUAF error accessing SYSUAF file Explanation: Could not access the SYSUAF file. User Action: Note accompanying error message for more details. 6 EXP_ERRUAFGET error getting SYSUAF information Explanation: Error accessing information in the SYSUAF file. User Action: Note accompanying error message for more information. 6 EXP_EXCADD principal added to DCE EXPORT exclude list Explanation: Principal successfully added to the DCE EXPORT exclude list. User Action: None. 6 EXP_EXCDEL principal removed from DCE EXPORT exclude list Explanation: Principal successfully deleted from the DCE EXPORT exclude list. User Action: None. 6 EXP_EXCLUDED principal has been excluded from OpenVMS Explanation: Unable to export because it is on the DCE EXPORT exclude list. This message is displayed only if /INFORM is specified on the EXPORT command line. User Action: If incorrectly excluded, use DELETE/EXCLUDE to remove it from the DCE EXPORT exclude list and reexport. 6 EXP_GRPUICFULL no member UIC available in specified group Explanation: No more members available in the specified group. User Action: Use another group UIC if possible. 6 EXP_INDCEUAF principal already in DCE$UAF Explanation: Could not add already existing principal name to DCE$UAF. User Action: None. 6 EXP_INEXCLUDE principal already in DCE EXPORT exclude file Explanation: An attempt was made to add an already existing principal name to the DCE EXPORT exclude file. User Action: None. 6 EXP_INITERROR initialization error Explanation: Error during initialization phase for DCE EXPORT. User Action: Note accompanying error message for more details. 6 EXP_INITWAIT initializing..... Explanation: DCE EXPORT in initialization phase. User Action: None. 6 EXP_INPREQ input required! Explanation: Input not entered where mandatory. User Action: Provide input. 6 EXP_INTERROR internal error Explanation: Internal error in DCE EXPORT. User Action: Note accompanying error message for more details or submit a Quality Assurance Report (QAR). 6 EXP_INTINPDEV internal error opening input device Explanation: Error accessing SYS$INPUT. User Action: Check user runtime configuration. Refer to appropriate OpenVMS documentation for more information. 6 EXP_INVGRPUIC invalid group UIC Explanation: Group UIC entered is invalid (format if value, name if identifier). User Action: Enter valid group UIC. 6 EXP_INVMEMUIC invalid member UIC Explanation: Member UIC entered is out of range or of invalid format. User Action: Enter valid member UIC. 6 EXP_INVMS principal already exported to OpenVMS Explanation: A record for already exists in the DCE$UAF file indicating that is has already been exported. User Action: None. 6 EXP_INVPASSWD password validation failed. Please retry Explanation: Password validation failed while entering password for the OpenVMS account to be created. User Action: Enter valid password. 6 EXP_INVPWDLEN password length must be between and characters Explanation: The user specified password for the OpenVMS account is outside of the defined range. User Action: Specify a password of length between and 6 EXP_NAMEINUSE OpenVMS username already mapped to another DCE principal Explanation: OpenVMS username specified is already associated with another DCE principal in the DCE$UAF file. User Action: Specify a username that is not associated with a DCE princi- pal. Use the DCE$UAF utility to search the DCE$UAF file for usernames and associated DCE principal names. 6 EXP_NODCEUAF unable to open DCE authorization file Explanation: Error occurred while attempting to open the DCE$UAF file. User Action: See accompanying message for details. 6 EXP_NOEXCUSR no excluded users Explanation: No principal names listed in the DCE EXPORT exclude file. User Action: None. 6 EXP_NOSCHUSR no principal in DCE registry Explanation: Principal requested for export does not exist in the DCE registry. User Action: Use valid DCE principal name. Use the DCE tool RGY_EDIT to view DCE principal names. 6 EXP_NOSUCHEXC no such principal in DCE EXPORT exclude file Explanation: Requested principal does not exist in DCE EXPORT exclude file. User Action: Use the SHOW/EXCLUDE command to list names in the exclude file. 6 EXP_NOSUCHPR no DCE account Explanation: An attempt was made to export a nonexistent DCE principal. User Action: Specify a valid DCE principal name. Use the DCE tool RGY_EDIT to view the DCE principals. 6 EXP_NOTINEXC principal not in DCE EXPORT exclude file Explanation: An attempt was made to access a nonexistent record in the DCE EXPORT file. User Action: Use SHOW/EXCLUDE to see the contents of the exclude file. 6 EXP_NOVMSUSR no OpenVMS user Explanation: A nonexistent OpenVMS username was specified with the /LIKE qualifier. User Action: Specify a valid OpenVMS username. 6 EXP_NXTMEMUIC error finding next available member UIC Explanation: Could not find the next available member UIC in the group specified. User Action: Note the accompanying error message for more details. 6 EXP_OUTOPNERR error opening alternate output Explanation: Could not access file name specified with /OUTPUT qualifier. User Action: Note accompanying error message for more details. 6 EXP_SEEFILE see file for error messages Explanation: Error(s) occurred while creating the OpenVMS account but EXPORT was unable to display the error messages. The user is asked to read the file for the error messages. User Action: Read the file for error messages. 6 EXP_TIMERR DCE time configuration error Explanation: Time configuration is incorrect on the DCE system. User Action: Refer to the Troubleshooting chapter in the HP DCE for OpenVMS Alpha and OpenVMS I64 Product Guide. 6 EXP_TOOLONG input for too long Explanation: Value of is longer than expected maximum size of value. User Action: Enter a value that is within the valid size range. 6 EXP_USERERR error getting input from user Explanation: User entered invalid input. User Action: Enter valid input. 5 ADD Adds DCE principal names. The ADD command can only be used with the following qualifier: o ADD/EXCLUDE Adds a DCE principal name to the EXPORT exclude list (see /EXCLUDE). /EXCLUDE Adds a DCE principal name to the EXPORT exclude list. Format: ADD/EXCLUDE PRINCIPAL Parameters principal Specifies the DCE principal name to be added to the EXPORT exclude list. If the principal name contains lowercase characters, spaces, or other special characters, enclose the entire string in quotes. 5 DELETE Deletes DCE principal names. The DELETE command can only be used with the following qualifier: o DELETE/EXCLUDE Deletes a DCE principal name from the EXPORT exclude list (see /EXCLUDE). /EXCLUDE Deletes a DCE principal name from the EXPORT exclude list. Format: DELETE/EXCLUDE PRINCIPAL Parameters principal Specifies the DCE principal name to be deleted from the EXPORT exclude list. If the principal name contains lowercase characters, spaces, or other special characters, enclose the entire string is quotes. 5 EXIT Exits the EXPORT utility. You can also exit EXPORT by pressing the Ctrl/Z key. Format: EXIT 5 EXPORT The EXPORT command is used to create OpenVMS accounts in the OpenVMS system authorization file (SYSUAF) based on existing accounts in the DCE registry. Format: EXPORT DCE-ACCOUNT-NAME Qualifiers Defaults /[NO]ADD_IDENTIFIERS /ADD_IDENTIFIERS /[NO]CONFIRM /DCE_LOGIN=(keyword=value[,...]) /[NO]EXCLUDE /NOEXCLUDE /[NO]INFORM /INFORM /[NO]INTERACTIVE /INTERACTIVE /OUTPUT[=output] /OUTPUT=SYS$OUTPUT: /[NO]RECAP /NORECAP /[NO]TEST_ONLY /NOTEST_ONLY /[NO]WILD /WILD Data Qualifiers Defaults /[NO]ACCOUNT=account /ACCOUNT=dce-group-name /DEVICE=device Taken from /LIKE account /DIRECTORY=directory /DIRECTORY=vms-username /GROUP_UIC=group_uic /LIKE=vms-account /LIKE=DEFAULT /MEMBER_UIC=member_uic Next available within UIC group /[NO]OWNER=owner /OWNER=dce-principal-name /PASSWORD=passwd None /[NO]QUOTA=n /QUOTA=1000 /USERNAME=username /USERNAME=dce-principal-name 6 Parameters dce-account-name Specifies the name of the DCE account that is to be exported. If the DCE account name contains lowercase characters, spaces or other special characters then enclose the name in quotes. If an asterisk is specified in place of the dce-account- name then all accounts from the registry are selected. 6 Qualifiers /CONFIRM /CONFIRM /NOCONFIRM Controls whether the EXPORT command asks for confirmation before creating the OpenVMS account. In interactive mode the default is /CONFIRM. In noninteractive mode the default is /NOCONFIRM. /DCE_LOGIN=(keyword=value[,...]) /DCE_LOGIN=(keyword=value[,...]) Provides DCE account details for accounts that are authorized to read pricipals and accounts from the DCE registry. Valid keywords for the DCE_LOGIN qualifier are as follows: Keyword Description PRINCIPAL The principal name to be used for authentication purposes when reading accounts and/or principals from the DCE registry. If you do not specify a principal with this qualifier you are prompted for one interactively. PASSWORD The password associated with the principal name that was specified by the PRINCIPAL keyword. If you do not specify a password with this qualifier you are prompted for one interactively. If you do not specify a principal or password with this qualifi- er, you are prompted for them interactively, regardless of whether or not you are running in interactive mode. This infor- mation need be entered only once per session, on the first EXPORT command.Subsequent EXPORT commands within the same session do not require that you to reenter this information. If you are an interactive user and you do not specify the PASSWORD keyword, EXPORT prompts you for your password. The advantage in this is the password is not echoed and therefore does not appear on your terminal. /EXCLUDE /EXCLUDE /NOEXCLUDE (default) Determines whether the DCE account is exported to OpenVMS. If the DCE account is not exported, the OpenVMS account is not created and an entry is created in the EXPORT exclude file for the specified DCE account. /INFORM /INFORM (default) /NOINFORM Determines whether the user is informed of DCE accounts that would have been selected for export, but are not selected. (The reasons that accounts are not selected for export are that they have already been exported (for example, they have an entry in the DCE$UAF) or that they exist in the EXPORT exclude file.) /INTERACTIVE (default) /INTERACTIVE (default) /NOINTERACTIVE Controls whether an interactive or noninteractive export is performed. In interactive mode, a series of questions is asked and the user's responses are used to determine the account details. This mode is well suited to interactive users. In noninteractive mode, all input is supplied through the data qualifiers, and any missing or conflicting data causes the OpenVMS account to not be created. This mode is well suited to command files and batch jobs. Data qualifiers can be specified in interactive mode. In this case the data they provide is used to provide the default answers to the relevant questions. All questions are still asked. /OUTPUT[=output] /OUTPUT[=output] Defines where all program output should be written. The default is SYS$OUTPUT:. /RECAP /RECAP /NORECAP (default) If /RECAP is specified details of the OpenVMS account are dis- played before it is actually created. When /CONFIRM is also specified the account details are displayed immediately before the confirmation request. /TEST_ONLY /TEST_ONLY /NOTEST_ONLY (default) If /TEST_ONLY is specified, OpenVMS accounts, identifiers, and DCE$UAF entries are not created. All other functions operate normally. /WILD /WILD (default) /NOWILD Specifies whether or not standard VMS wildcarding is to be applied to dce-account-name. The default is /WILD which means a dce-account-name of "SM*" is interpreted as meaning "export any account starting SM". If /NOWILD is specified the dce-account-name "SM*" is exported. 6 Data_Qualifiers /ACCOUNT=account /ACCOUNT=account (default) [NO]ACCOUNT Specifies the account string for the OpenVMS account (same as /ACCOUNT in AUTHORIZE). The account is a string of 1 to 8 alphanumeric characters. If this qualifier is not specified, the DCE account's group name is used (truncated to 8 characters if necessary). If no account field is required then specify /NOACCOUNT. /DEVICE=device /DEVICE=device Specifies the name of the OpenVMS account's default device at login. The device-name is a string of 1 to 31 alphanumeric characters. If you omit the colon from the device-name value, a colon is automatically appended. The default device is copy the device field from the account specified by the /LIKE qualifier. /DIRECTORY=directory /DIRECTORY=directory Specifies the default directory name for the DIRECTORY field of the OpenVMS SYSUAF record. The directory name can be 1 to 63 alphanumeric characters. If you do not enclose the directory name in brackets, EXPORT adds the brackets for you. The default directory name is [username] where username is the OpenVMS account's username. /GROUP_UIC=group_uic /GROUP_UIC=group_uic Specifies the group part of the UIC for the OpenVMS account. GROUP_UIC can be specified as an octal group UIC code or as an existing group UIC identifier. If specified as an octal number, it must be in the range 1 to 37776 (octal). The default is to take the OpenVMS account's ACCOUNT field, convert it to uppercase, and interpret this as a group UIC identifier. If such an identifier does not exist then a similar translation is attempted for the DCE account's group name. If neither identifiers exist, the group UIC is derived from the OpenVMS account specified by the /LIKE qualifier. /LIKE=vms-account /LIKE=vms-account Specifies an existing OpenVMS account that is to be used as the basis for the OpenVMS account that is being created. Any fields not specified on the EXPORT command line, as well as all quotas, privileges, etc, are inherited from the /LIKE account. The default is DEFAULT (as it is in AUTHORIZE). /MEMBER_UIC=member_uic /MEMBER_UIC=member_uic Specifies the member part of the UIC for the OpenVMS account. MEMBER_UIC should be specified as an octal number within the range 0 to 177776 (octal). The default is to use the first available member UIC within the group UIC (as specified by /GROUP_UIC). For example, if the selected group is 150 and that group has members 1, 2, 5 and 6 already defined, then the new uic would be [150,3]. /OWNER=owner (default) /OWNER=owner (default) /NOOWNER Specifies the owner string for the OpenVMS account (same as /OWNER in AUTHORIZE). The owner is a string of 1 to 31 characters. If this qualifier is not specified, the DCE account's principal name is used (truncated to 31 characters if necessary). If no owner field is required, specify /NOOWNER. /PASSWORD=passwd /PASSWORD=passwd Specifies the password for the OpenVMS account. Passwords contain from 0 to 32 characters and can include alphanumeric characters, dollar signs, and underscores. Passwords are not case-sensitive. If you do not specify a password, the account is created without a valid OpenVMS password. /QUOTA=quota /QUOTA=quota (default) /NOQUOTA Specifies the disk quota for the device specified by /DEVICE to be given to the OpenVMS account (if quotas are enabled on that volume). The default is 1000 blocks. If quotas are not enabled on the device specified by /DEVICE, or if /NOQUOTA is specified, then no quota is given. /USERNAME=username /USERNAME=username Specifies the username for the OpenVMS account. The username is a string of 1 to 12 alphanumeric characters and can contain underscores. If this qualifier is not specified, the DCE account's principal name is used (truncated to 12 characters and uppercased). 5 SHOW Displays DCE principal names. The SHOW command can only be used with the following qualifier: o SHOW/EXCLUDE Displays DCE principal names in the EXPORT exclude list (see /EXCLUDE). /EXCLUDE Displays DCE principal names in the EXPORT exclude list. Format: SHOW/EXCLUDE [PRINCIPAL] Qualifiers Defaults /ALL /OUTPUT=output /OUTPUT=SYS$OUTPUT: 6 Parameters principal Specifies the name of the DCE principal to be displayed from the EXPORT exclude list. Full OpenVMS wildcarding is allowed. If the principal name contains lowercase characters, spaces, or other special characters, enclose the entire string is quotes. If /ALL is on the command line, do not specify a principal name. 6 Qualifiers /ALL /ALL Specifies that all EXPORT exclude entries are to be displayed. If you do not specify principal, then /ALL is assumed. /OUTPUT=output /OUTPUT=output Determines where the output is written. The default is SYS$OUTPUT:. 4 DCE$IMPORT The DCE IMPORT utility allows you to create principal and account entries in a DCE registry based on accounts in an existing OpenVMS authorization file. It is used for the following purposes: o To populate the DCE registry when a new DCE cell is first established o To add entries to an existing DCE registry when a new OpenVMS system joins an existing DCE cell o To add entries to an existing DCE registry when new users have joined an OpenVMS sytem that is already part of an existing DCE cell The DCE IMPORT utility also creates and maintains an exclude list. The exclude list contains the OpenVMS usernames of users who do not have, and do not require, a DCE account. This feature allows DCE IMPORT to skip over these users during DCE IMPORT operations. NOTE: The DCE IMPORT utility described in this section cannot be satisfied by the import function shipped with OSF DCE because of substantial differences between OpenVMS and UNIX user registry data. Passwords cannot be imported. Instead, the automatic synchronization feature that occurs during integrated login is used to import user passwords. See the HP DCE for OpenVMS Alpha and OpenVMS I64 Reference Guide for detailed descriptions of the DCE IMPORT commands. RELATED INFORMATION COMMANDS: DCE$EXPORT 5 File_Info The DCE DCE IMPORT utility is shipped as an OpenVMS executable image named DCE$IMPORT.EXE. The image resides in the SYS$SYSTEM directory. The DCE IMPORT exclude file is named by default DCE$IMPORT_EXCLUDE.DAT and also resides in SYS$SYSTEM. You can change the name or location, or both, of this file by defining the logical name DCE$IMPORT_EXCLUDE to point to the new filename and location. 5 Running_IMPORT The DCE IMPORT utility allows system administrators to create princi- pal and account entries in a DCE registry based on accounts in SYSUAF. Integrated Login provides two methods of running the DCE IMPORT utility, as follows. o By invoking the DCE IMPORT utility using a predefined symbol. $ IMPORT IMPORT> You can also specify a single DCE IMPORT command on the command line. Control returns to DCL after the command is executed. $ IMPORT command SYS$COMMON:[SYSMGR]DCE$DEFINE_REQUIRED_COMMANDS.COM defines the DCE symbol IMPORT which is used to invoke the DCE IMPORT utility. If this symbol is not defined in your environment, you can define the symbol as follows: $ IMPORT :== $SYS$SYSTEM:DCE$IMPORT o By issuing the RUN command. $ RUN SYS$SYSTEM:DCE$IMPORT IMPORT> 5 Messages 6 IMP_ACCEXISTS account for already exists in DCE Explanation: An attempt has been made to recreate an account for in the DCE registry. User Action: None. This is a warning indicating that this suboperation in the IMPORT operation was previously performed. 6 IMP_ADDDCE username successfully imported into DCE Explanation: A DCE account has been successfully created for OpenVMS username . User Action: None. 6 IMP_ADDDCEACC account for successfully added to DCE Explanation: A DCE account was successfully created for . User Action: None. This is an informational message displayed only if /INFORM is specified on the DCE IMPORT command line. 6 IMP_ADDDCEPRN principal successfully added to DCE Explanation: Principal record successfully created in the DCE registry. User Action: None. This is an informational message displayed only when /INFORM is specified on the DCE IMPORT command line. 6 IMP_ADDDCEUAF username successfully added to DCE$UAF Explanation: Username successfully added to the DCE$UAF file. User Action: None. This is an informational message displayed only if /INFORM is specified on the DCE IMPORT command line. 6 IMP_BINDERR error binding to DCE security registry Explanation: Unable to bind to the DCE security server. User Action: Note accompanying DCE error message for more details. 6 IMP_CREDCEUAF created new DCE$UAF file Explanation: A new DCE$UAF file was created. User Action: None. 6 IMP_DCEERR Explanation: Accompanying DCE error message supplied with other DCE IMPORT error messages. User Action: Use this message to determine the cause of the problem. 6 IMP_DCELOGIN error in DCE login Explanation: An error occurred during DCE login. User Action: Enter a valid DCE username and password when prompted by DCE IMPORT. 6 IMP_DCEUAFERR error searching DCE$UAF Explanation: An error occurred while searching the DCE$UAF file. User Action: Note the accompanying error message for more details. 6 IMP_DELACC account for principal deleted from DCE Explanation: DCE account for was deleted from the DCE registry. This occurs when an atomic IMPORT operation fails during one of its suboperations. Such failure prompts a backout of all suboperations successfully performed during this IMPORT operation. Deleting the account is one such backout operation. User Action: None. This is an informational message displayed only when /INFORM is specified on the DCE IMPORT command line. 6 IMP_DELDCEUAF username successfully deleted from DCE$UAF Explanation: Username deleted from DCE$UAF file. User Action: None. This is an informational message displayed only if /INFORM is specified on the DCE IMPORT command line. 6 IMP_DELFRGRP principal from group Explanation: Principal was deleted from in the DCE registry. This occurs when an atomic IMPORT operation fails during one of its suboperations. Such failure prompts a backout of all suboperations successfully performed during this IMPORT operation. Deleting the principal from the group is one such backout operation. User Action: None. This is an informational message displayed only when /INFORM is specified on the DCE IMPORT command line. 6 IMP_DELFRORG principal deleted from organization Explanation: Principal was deleted from in the DCE registry. This occurs when an atomic IMPORT operation fails during one of its suboperations. Such failure prompts a backout of all suboperations successfully performed during this IMPORT operation. Deleting the principal from the organization is one such backout operation. User Action: None. This is an informational message displayed only when /INFORM is specified on the DCE IMPORT command line. 6 IMP_DELPRN principal deleted from DCE Explanation: Principal was deleted from the DCE registry. This occurs when an atomic IMPORT operation fails during one of its suboperations. Such failure prompts a backout of all suboperations successfully performed during this IMPORT operation. Deleting the principal is one such backout operation. User Action: None. This is an informational message displayed only when /INFORM is specified on the DCE IMPORT command line. 6 IMP_ERRADDGRP error adding principal to group Explanation: Could not add to in the DCE registry. User Action: Note the accompanying DCE error message for more details. 6 IMP_ERRADDORG error adding principal to organization Explanation: Could not add to in DCE registry. User Action: Note the accompanying DCE error message for more details. 6 IMP_ERRACCEXC error accessing DCE IMPORT exclude file Explanation: Could not access the DCE IMPORT exclude file. User Action: Note the accompanying error message for more details. 6 IMP_ERRADDEXC adding username to DCE IMPORT exclude file Explanation: Could not add the requested username to the DCE IMPORT exclude file. User Action: Note the accompanying error message for more details. 6 IMP_ERRADDUAF error adding username to DCE$UAF file Explanation: Could not add the imported username to the DCE$UAF file. User Action: Note the accompanying error message for more details. 6 IMP_ERRCRACC error creating account for Explanation: Could not create a DCE account for . User Action: Note the accompanying DCE error message for more details. 6 IMP_ERRCRDCEUAF error creating DCE authorization file Explanation: An error occurred while attempting to create the DCE$UAF file. User Action: See accompanying message for details. 6 IMP_ERRCRPRN error creating principal Explanation: Could not create a principal in the DCE registry. User Action: Note the accompanying DCE error message for more details. 6 IMP_ERRDCEUAF error accessing DCE authorization file Explanation: An error occurred while attempting to access the DCE$UAF file. User Action: See accompanying message for details. 6 IMP_ERRDELACC error deleting account for Explanation: Unable to delete account for from DCE registry. User Action: See accompanying DCE error message for more details. 6 IMP_ERRDELEXC error deleting username from DCE IMPORT exclude file Explanation: Could not remove requested username from the DCE IMPORT exclude file. User Action: Note the accompanying error message for more details. 6 IMP_ERRDELFRGRP error deleting principal from group Explanation: An error occurred while deleting from in the DCE registry. This delete operation is performed if the overall IMPORT operation failed and a backout of changes applied to the DCE registry is required. User Action: See accompanying DCE message for details. 6 IMP_ERRDELFRORG error deleting principal from organization Explanation: An error occurred while deleting from in the DCE registry. This delete operation is performed if the overall IMPORT operation failed and a backout of changes applied to the DCE registry is required. User Action: See accompanying DCE message for details. 6 IMP_ERRDELPRN error deleting principal Explanation: Unable to delete from DCE registry User Action: See accompanying DCE error message for more details 6 IMP_ERRDELUAF error deleting username from DCE$UAF file Explanation: Could not delete a username from the DCE$UAF file. User Action: Note the accompanying error message for more details. 6 IMP_ERRCHGAUT error changing account authorization policy Explanation: Could not change the DCE account's authorization policy. User Action: Note the accompanying DCE error message for more details. 6 IMP_ERRSPAWN error spawning sub-process Explanation: An error occurred while spawning a subprocess on the SPAWN command. User Action: Refer to appropriate OpenVMS documentation for resolution. 6 IMP_ERRSYSUAF error accessing SYSUAF file Explanation: Could not access the OpenVMS SYSUAF file. User Action: See accompanying OpenVMS or RMS error message for more details. 6 IMP_EXCADD username added to DCE IMPORT exclude list Explanation: Username successfully added to the DCE IMPORT exclude file. A DCE account will not be created for this username. User Action: None. 6 IMP_EXCDEL username removed from DCE IMPORT exclude list Explanation: Username successfully removed from DCE IMPORT exclude file. A subsequent IMPORT session could be used to create a DCE account for this username. User Action: None. 6 IMP_EXCLUDED username has been excluded from DCE Explanation: Username cannot be imported since it has been excluded from the DCE registry. User Action: None. This is an informational message displayed when /INFORM is specified on the DCE IMPORT command line. 6 IMP_INDCE username already imported into DCE Explanation: An import operation was attempted on an already imported OpenVMS username. User Action: None. This is an informational message displayed only when /INFORM is specified on the DCE IMPORT command line. 6 IMP_INDCEUAF user already in DCE$UAF Explanation: Username already exists in the DCE$UAF.DAT file. User Action: None. This is a warning indicating that this suboperation in the IMPORT operation was previously performed. 6 IMP_INEXCLUDE username already in DCE IMPORT exclude file Explanation: Username has previously been added to the DCE IMPORT exclude file. User Action: None. This informational message is displayed when an exclude operation is attempted on an already excluded username and is displayed only when /INFORM is specified on the DCE IMPORT command line. 6 IMP_INTINPDEV internal error opening input device Explanation: Error opening SYS$INPUT. User Action: Verify user runtime environment. See to appropriate OpenVMS documentation for more details. 6 IMP_INITERROR initialization error Explanation: An error occurred during DCE IMPORT's initialization phase. User Action: Note error messages accompanying or directly preceding this message. 6 IMP_INITWAIT initializing..... Explanation: DCE IMPORT is in initialization mode. User Action: None. 6 IMP_INVPASSWD password validation failed. Please retry Explanation: The password entered when prompted for a retype does not match the originally entered password. User Action: Enter correct password for original and retype entry. 6 IMP_INPREQ input required! Explanation: Input not entered where input was mandatory. User Action: Provide required input. 6 IMP_INTERROR internal error Explanation: DCE IMPORT internal error occurred. User Action: Contact your support engineer or Submit a Quality Assurance Report (QAR). 6 IMP_INVDATETM invalid date/time Explanation: Date/time entered has invalid format. User Action: Enter date/time in standard format (dd-MMM-yyyy hh:mm:ss). 6 IMP_NODCEUAF unable to open DCE authorization file Explanation: Error occurred while attempting to open the DCE$UAF file User Action: See accompanying message for details. 6 IMP_NOEXCUSR no excluded users Explanation: No users listed in DCE IMPORT exclude file. User Action: None. 6 IMP_NOGRP group name not specified Explanation: Mandatory qualifier /GROUP not specified during a noninter- active IMPORT session. User Action: Provide the /GROUP qualifier with the group name on the command line. 6 IMP_NOORG organization name not specified Explanation: Mandatory qualifier /ORGANIZATION not specified during a noninteractive IMPORT session. User Action: Provide the /ORGANIZATION qualifier with the organiation name on the command line. 6 IMP_NOPRIN principal does not exist in DCE Registry Explanation: Principal does not exist in the DCE Registry. This means that does not have a corresponding OpenVMS username/account. User Action: None. 6 IMP_NOSUCHEXC no such username in exclude file Explanation: Username specified does not exist in DCE IMPORT's exclude file. User Action: Specify username that exists in DCE IMPORT's exclude file. Enter command SHOW/EXCLUDE to display the entire exclude list. 6 IMP_NOSUCHGRP no group . Please choose a valid group Explanation: The group name specified is nonexistent in the DCE registry. User Action: Choose a valid group name. Use the DCE tool RGY_EDIT to search the DCE registry for group names. 6 IMP_NOSUCHORG no organization . Please choose a valid organization Explanation: The organization name specified is nonexistent in the DCE registry. User Action: Choose a valid organization name. Use the DCE tool RGY_EDIT to search the DCE registry for organization names. 6 IMP_NOSCHPRM corresponding primary principal not found in DCE Explanation: The DCE principal name specified as the primary principal while attempting to create an alias principal name is non- existent in the DCE registry. User Action: Use the correct DCE principal name. Use the DCE tool RGY_EDIT to view the DCE registry. 6 IMP_NOSCHUSR OpenVMS username does not exist on this system Explanation: An attempt was made to import a nonexistent OpenVMS user. User Action: Choose a valid OpenVMS user. 6 IMP_OUTOPNERR error opening alternate output Explanation: Could not access output medium User Action: If /OUTPUT was specified, verify the file name supplied with /OUTPUT. If /OUTPUT was not specified, check user runtime environment. See appropriate OpenVMS documentation for more details. 6 IMP_PREXISTS principal already exists in DCE Explanation: An attempt has been made to add to the DCE registry. User Action: None. This is a warning indicating that this suboperation in the IMPORT operation was previously performed. 6 IMP_PRINGRP principal already exists in group Explanation: An attempt was made to add to DCE group when it already was a member of the group. This action was attempted during an import operation. User Action: None. This is an informational message displayed only when /INFORM is specified on the DCE IMPORT command line. 6 IMP_PRINORG principal already exists in organization Explanation: An attempt was made to add to DCE organization when it was already a member of that organization. This action was attempted during an import operation. User Action: None. This is an informational message displayed only when /INFORM is specified on the DCE IMPORT command line. 6 IMP_PRINUSE principal in use by another OpenVMS username Explanation: The DCE principal name specified for the OpenVMS username being imported is associated with another OpenVMS username. User Action: Choose a DCE principal name that is not associated with any OpenVMS username. 6 IMP_RANGEERR error in entry! Number must be between 1 and 65535 Explanation: The value entered for quota is not within the desired range. User Action: Enter a number between 1 and 65535. 6 IMP_TIMERR DCE time configuration error Explanation: Time configuration incorrect on the DCE system. User Action: Refer to the Troubleshooting chapter in the HP DCE for OpenVMS Alpha and OpenVMS I64 Product Guide. 6 IMP_TOOLONG input for too long Explanation: Value of is longer than expected maximum size of value. User Action: Enter a value that is within the valid size range. 6 IMP_USERERR error getting input from user Explanation: Error occurred while getting user input. User Action: Provide valid input. 5 ADD Adds OpenVMS usernames. The ADD command can only be used with the following qualifier: o ADD/EXCLUDE Adds an OpenVMS username to the IMPORT exclude list (see /EXCLUDE). /EXCLUDE Adds an OpenVMS username to the IMPORT exclude list. Format: ADD/EXCLUDE USERNAME Parameters username Specifies the name of the OpenVMS account to be added to the IMPORT exclude list. 5 DELETE Deletes OpenVMS usernames. The DELETE command can only be used with the following qualifier: o DELETE/EXCLUDE Deletes an OpenVMS username from the IMPORT exclude list (see /EXCLUDE). /EXCLUDE Deletes an OpenVMS username from the IMPORT exclude list. Format: DELETE/EXCLUDE USERNAME Parameters username Specifies the name of the OpenVMS account to be deleted from the IMPORT exclude list. 5 EXIT Exits the IMPORT utility. You can also exit IMPORT by pressing the Ctrl/Z key. Format: EXIT 5 IMPORT The IMPORT command is used to create DCE accounts based on OpenVMS accounts from an existing System Authorization File (SYSUAF). Format: IMPORT VMS-USERNAME Qualifiers Defaults /[NO]CONFIRM /DCE_LOGIN=(keyword=value,...) /[NO]IMPORT /IMPORT /[NO]EXCLUDE /NOEXCLUDE /[NO]INFORM /INFORM /[NO]INTERACTIVE /INTERACTIVE /MY_PASSWORD=passwd None /OUTPUT[=output] /OUTPUT=SYS$OUTPUT: /[NO]RECAP /NORECAP /[NO]TEST_ONLY /NOTEST_ONLY Data Qualifiers Defaults /[NO]EXPIRATION_DATE=d /NOEXPIRATION_DATE /FLAGS=flags /GOOD_SINCE_DATE=date /GOOD_SINCE_DATE=now /GROUP=group "none" /HOME_DIRECTORY=string None /LIFETIME=hours Taken from registry authorization policy /LOGIN_SHELL=string None /MISCELLANEOUS=string None /ORGANIZATION=organiza "none" /PASSWORD=passwd No valid password /PRINCIPAL=principal /RENEWABLE_LIFETIME=ho Taken from registry authorization policy 6 Parameters vms-username Specifies the name of the OpenVMS account that is to be imported. If an asterisk is specified in place of the vms-username, all accounts from the OpenVMS system authorization file are selected. 6 Qualifiers /CONFIRM /CONFIRM /NOCONFIRM Controls whether the IMPORT command asks for confirmation before creating a DCE principal or account, or both. In interactive mode the default is /CONFIRM. In non- interactive mode the default is /NOCONFIRM. /DCE_LOGIN=(keyword=valud[,...]) /DCE_LOGIN=(keyword=valud[,...]) Provides DCE account details for accounts that are authorized to create pricipals and accounts in the DCE registry. Valid keywords for the DCE_LOGIN qualifier are as follows: Keyword Description PRINCIPAL The principal name to be used for authentication purposes when creating accounts and/or principals in the DCE registry. If you do not specify a principal with this qualifier you are prompted for one interactively. PASSWORD The password associated with the principal name that was specified by the PRINCIPAL keyword. If you do not specify a password with this qualifier you are prompted for one interactively. If you do not specify a principal or password with this qualifier, you are prompted for them interactively, regardless of whether or not you are running in interactive mode. This information need be entered only once per session, on the first IMPORT command. Subsequent IMPORT commands within the same session do not require you to reenter this information. If you are an interactive user and you do not specify the PASSWORD keyword, IMPORT prompts you for your password. The advantage in this is the password is not echoed and therefore does not appear on your terminal. /EXCLUDE /EXCLUDE /NOEXCLUDE (default) Determines whether or not the OpenVMS account is imported to the DCE registry. If the OpenVMS account is not imported then the DCE account is not created and instead an entry is created in the IMPORT exclude file for the specified OpenVMS account. /INFORM /INFORM (default) /NOINFORM Determines whether or not the user is informed of OpenVMS accounts that would have been selected for import, but are not because they either have already been imported (for example, they have an entry in the DCE$UAF) or they have an entry in the IMPORT exclude file. /INTERACTIVE /INTERACTIVE (default) /NOINTERACTIVE Controls whether an interactive or noninteractive import is performed. In interactive mode, a series of questions is asked and the user's responses are used to determine the account details. This mode is well suited to interactive users. In noninteractive mode, all input is supplied through the data qualifiers, and any missing or conflicting data causes the DCE account to not be created. This mode is well suited to command files and batch jobs. Data qualifiers can be specified in interactive mode. In this case the data they provide is used to provide the default answers to the relevant questions. All questions are still asked. /MY_PASSWORD=passwd /MY_PASSWORD=passwd DCE requires that you specify your current DCE password for authentication purposes. If you do not specify your DCE password with this qualifier you are prompted for it interactively, regardless of if you are running in interactive mode or not. Omitting this qualifier and allowing IMPORT to prompt you for your DCE password has the advantage that in this case the password is not echoed and does therefore not appear on your terminal if you are an interactive user. OUTPUT[=output] /OUTPUT[=output] Defines where all program output should be written. The default is SYS$OUTPUT:. /RECAP /RECAP /NORECAP (default) If /RECAP is specified details of the DCE account are displayed before it is actually created. When /CONFIRM is also specified the account details are displayed immediately before the confirmation request. /TEST_ONLY /TEST_ONLY /NOTEST_ONLY (default) If /TEST_ONLY is specified, DCE accounts and DCE$UAF entries are not created. All other functions operate normally. 6 Data_Qualifiers /EXPIRATION_DATE=date /EXPIRATION_DATE=date /NOEXPIRATION_DATE (default) Specifies the expiration date for the DCE account. If not specified, or if /NOEXPIRATION_DATE is specified, then the DCE account is created without an expiration date. /FLAGS=([no]keyword[,...]) /FLAGS=([no]keyword[,...]) Specifies several attributes of the DCE account. The keywords you can specify are: Keyword Description ACCOUNT_VALID A flag that is set to determine account validity. An account without this flag set is invalid and cannot log in. The default is ACCOUNT_VALID. CLIENT A flag that is set to indicate whether or not the account is for a principal that can act as a client. The default is CLIENT. DUPLICATE_KEYS A flag that is set to determine if tickets issued to the account's principal can have duplicate keys. The default is NODUPLICATE_KEYS. FORWARDABLE_ A flag that is set to determine whether a CERTIFICATES new ticket-granting ticket with a network address that differs from the present ticket-granting ticket network address can be issued to the account's principal. (The Proxiable Certificate Flag performs the same function for service tickets.) The default is FORWARDABLE_CERTIFICATES. PASSWORD_VALID A flag that is set to determine whether the current password is valid. If this flag is not set, the next time the principal logs in to the DCE account, the system prompts the principal to change his password. The default is PASSWORD_VALID. POSTDATED_ A flag that is set to determine if tickets CERTIFICATES with a start time some time in the future can be issued to the account's principal. The default is NOPOSTDATED_CERTIFICATES. PROXIABLE_ A flag that is set to determine whether or CERTIFICATE not a new ticket with a different network address than the present ticket can be issued to the account's principal. (The Forwardable Certificate Flag performs the same function for ticket-granting tickets.) The default is NOPROXIABLE_CERTIFICATE. RENEWABLE_ A flag that is set to determine if the CERTIFICATE ticket-granting ticket issued to the account's principal can be renewed.If this flag is set the authentication service renews the ticket-granting ticket if its lifetime is valid. The default is RENEWABLE_CERTIFICATE. SERVER A flag that is set to indicate whether or not the account is for a principal that can act as a server. The default is SERVER. TGT_ A flag that is set to determine whether AUTHENTICATION or not tickets issued to the account's principal can use the ticket-granting ticket authentication mechanism. The default is TGT_AUTHENTICATION. /GOOD_SINCE_DATE=date /GOOD_SINCE_DATE=date Specifies the date and time that the account was known to be in an uncompromised state. If not specified, the Good Since Date is set to the current date and time. /GROUP=group /GROUP=group Specifies the name of an existing DCE group that is associated with the account being created. Note that if the group does not exist it is not be created by IMPORT. The default group name is "none". /HOME_DIRECTORY=string /HOME_DIRECTORY=string Specifies the directory in which the principal is placed at login. If not specified the DCE account is created without a Home Directory. /LIFETIME=hours /LIFETIME=hours Specifies the maximum amount of time, in hours, that a ticket can be valid. If not specified the Maximum Certificate Lifetime defined as registry authorization policy is used. /LOGIN_SHELL=string /LOGIN_SHELL=string Specifies the shell that is executed when a principal logs in. If not specified the DCE account is created without a login shell. /MISCELLANEOUS=string /MISCELLANEOUS=string Specifies a text string that is typically used to describe the use of the account. If not specified the DCE account is created without a miscellaneous value. /ORGANIZATION=organization /ORGANIZATION=organization Specifies the name of an existing DCE organization that is associated with the account being created. Note that if the organization does not exist it is not be created by IMPORT. The default organization name is "none". /PASSWORD=passwd /PASSWORD=passwd Specifies the password to be assigned to the DCE account. If not specified the DCE account is created without a valid DCE password. /PRINCIPAL=(keyword[,...]) /PRINCIPAL=(keyword[,...]) Specifies the principal that is associated with the DCE account that is being created. If an existing principal is to be associated with the DCE account being created then you need only specify NAME (and ALIAS if its an alias principal). The other keywords are only used when a new principal is created. The keywords you can specify are: Keyword Description ALIAS Specifies that the principal defined by the NAME keyword is an alias. By default the name is considered a primary principal. CASE=keyword Specifies how the principal name should be Formatted. For example, to specify that the principal name should be all lowercase, use /PRINCIPAL=CASE=LOWERCASE. Possible keywords are: NOEDIT Do not perform any Format:ting. This is the default. LOWERCASE[=n1[,n2]]Convert the principal name so that the first n1 characters and last n2 are lowercase, and the remainder are uppercase. If you do not specify a value for n1 then the entire principal is converted to lowercase. If you do not specify a value for n2 then 0 is used. UPPERCASE[=n1[,n2]]Convert the principal name so that the first n1 characters and last n2 are uppercase, and the remainder are lowercase. If you do not specify a value for n1 then the entire principal is converted to uppercase. If you do not specify a value for n2 then 0 is used. The default is NOEDIT. FULL_ An optional string that is used to more NAME=string fully qualify a primary name. If the name contains spaces, lowercase characters, or any other special characters, enclose the string in quotes. The default is no full name. NAME=name The standard name (primary or alias) that is associated with the DCE account. If the name contains spaces, lowercase characters, or any other special characters, enclose the string in quotes. The default is to take the username from the system authorization file (SYSUAF) record, edit it according to the CASE keyword, and then use this as the principal name. OBJECT_ The number of registry objects that can be CREATION_ created by the principal. QUOTA=number If you do not specify this keyword then no quota is established and the principal can create an unlimited number of registry objects. UNIX_ID=number The required UNIX ID that is associated with the principal. If a primary principal is being created you can omit the UNIX ID and one is generated automatically. If an alias principal is being created you must specify the UNIX ID of the corresponding primary principal. /RENEWABLE_LIFETIME=hours /RENEWABLE_LIFETIME=hours Specifies the amount of time, in hours, before a principal's ticket-granting ticket expires and that principal must log into the system again to reauthenticate and obtain another ticket-granting ticket. If not specified the Maximum Certificate Renewable Lifetime defined as registry authorization policy is used. 5 SHOW Displays OpenVMS usernames. The SHOW command can only be used with the following qualifier: o SHOW/EXCLUDE Displays OpenVMS usernames in the IMPORT exclude list (see /EXCLUDE). /EXCLUDE Displays OpenVMS usernames in the IMPORT exclude list. Format: SHOW/EXCLUDE [USERNAME] Qualifiers Defaults /ALL /OUTPUT=output /OUTPUT=SYS$OUTPUT: 6 Parameters username Specifies the name of the OpenVMS account to be displayed from the IMPORT exclude list. Full OpenVMS wildcarding is allowed. If /ALL is on the command line, do not specify a username. 6 Qualifiers /ALL /ALL Specifies that all IMPORT exclude entries are to be displayed. If you do not specify username, then /ALL is assumed. /OUTPUT=output /OUTPUT=output Determines where the output is written. The default is SYS$OUTPUT:. 4 rgy_edit NAME rgy_edit - Edits the registry database SYNOPSIS rgy_edit [[[-a | -p | -g | -o] [-s name] [-up[date]] [-v [-f] [name | -un[ix__number]] [-nq]] | -l] OPTIONS The following options are supplied when rgy_edit is invoked. You can specify only one of the options -a, -p, -g, and -o. If you specify the -l option, you can specify no other options. -a (default) Edits or views accounts. -p Edits or views principals. -g Edits or views groups. -o Edits or views organizations. -s Binds to the registry site specified by name. The name variable is either the fully qualified name of the cell that contains the registry to which you want access, or the fully qualified name of a specific registry server. -up[date] Binds to a read-write registry site in the cell specified by the -s option. -v Views the registry entry specified by name or unix_number. If no entry is specified, all entries are viewed. -f Displays in full the entry (or entries) selected by the -v option. The full entry includes all fields except the membership list and organization policy. -nq Specifies that delete operations will not be queried. The default is to prompt the user for verification when a delete operation is requested. -l Edits or views entries in local registry. NOTES With the exception of the following subcommands, this command is replaced at Revision 1.1 by the dcecp command. This command may be fully replaced by the dcecp command in a future release of DCE, and may no longer be supported at that time. + defaults + domain + scope + help + quit + exit + delete + purge + view DESCRIPTION The rgy_edit tool views and edits information in the registry database. You can invoke rgy_edit from any node. You can edit and view principals, groups, organization, accounts, and policies in the network registry (the default) or perform a subset of those functions on the local registry (using the -l option). Changes made by rgy_edit apply only to the registry. They do not apply to the local override file or the local password and group files, both of which can be edited manually. You can view and change only those registry objects to which you are granted the appropriate permissions. INVOKING RGY_EDIT When you invoke rgy_edit, it displays the following prompt: rgy_edit=> At this prompt, you can enter any of the rgy_edit subcommands, and rgy_edit will prompt you for the required information. Alternatively, you can enter the subcommand followed by all the options required to perform a specific operation. The rgy_edit command may prompt you for any required information you do not enter. SUBCOMMANDS In the rgy_edit subcommands that follow, use two double quotation marks with nothing in between to indicate a null fullname, password, misc, homedir, or shell. Use double quotation marks to embed spaces, or hyphens in fullname, misc, and homedir if you specify the argument on the command line. 5 pgo_commands PRINCIPAL, GROUP, AND ORGANIZATION SUBCOMMANDS Whether name applies to a principal, group, or organization depends on the domain in which you run rgy_edit. Use the do[main] subcommand (described in Miscellaneous Commands) to change domains. 6 view v[iew] [name] [-f] [-m] [-po] Views registry entries. The -f option displays entries in full (all fields except the membership list and organization policy). If you are viewing groups or organizations, -m displays the membership list. For principals, -m lists all groups of which the principal is a member, including groups that cannot appear in a project list. If you are viewing organizations, -po displays policy information. If you do not enter the -po option, rgy_edit shows only the organization's name and the UNIX number. 6 add a[dd] [principal_name [unix_number] [-f fullname] [-al] [-q quota]] a[dd] [group_name [unix_number] [-f fullname [-nl]]] [-al] ls a[dd] [organization_name [unix_number] [-f fullname]] Create a new name entry. If you do not specify principal_name, group_name, or organization name, the add subcommand prompts you for each field in the entry. If you are adding organizations, the command prompts you for policy information as well. If you specify only principal_name, group_name, or organization_name and no other arguments, the object's fullname defaults to "" (that is, blank), the object's UNIX number is assigned automatically, and the object's creation quota defaults to unlimited. Use the -al option to create an alias for an existing principal or group. No two principals or groups can have the same UNIX number, but a principal or group and all its aliases share the same UNIX number. The -al option creates an alias name for a principal or group and assigns the alias name the same UNIX number as the principal or group. The -q option specifies the principal's object creation quota, the total number of registry objects that can be created by the principal. If you do not specify this option, the object creation quota defaults to unlimited. For groups, the -nl option indicates that the group is not to be included on project lists; omitting this option allows the group to appear on project lists. 6 change c[hange] [principal_name [-n name] [-f fullname] [-al | -pr] [-q quota]] c[hange] [group_name [-n name] [-f fullname] [-nl | -l] ] [-al | -pr] c[hange] [organization_name [-n name] [-f fullname]] Changes a principal, group, or organization. Specify the entry to change with principal_name, group_name, or organization_name. If you do not specify a principal_name, group_name, or organization_name, the change subcommand prompts you for a name. If you do not specify any fields, the subcommand prompts you for each field in succession. To leave a field unchanged, press at the prompt. If you are changing organization entries in the interactive mode, the subcommand prompts you for policy information as well. Use -n name and -f fullname, to specify a new primary name or fullname, respectively. For principals and groups, the -al option changes a primary name into an alias, and the -pr option changes an alias into a primary name. This change can be made only from the command line, not in the interactive mode. The -q option specifies the total number of registry objects that can be created by the principal. For group entries, the -nl option disallows the group from appearing in project lists, while the -l option allows the group to appear in project lists. For organization entries, you can change policy information only in the interactive mode. Changes to a principal name are reflected in membership lists that contain the principal name. For example, if the principal ludwig is a member of the group composers and the principal name is changed to louis, the membership list for composers is automatically changed to include louis but not ludwig. For reserved names, you can change only fullname. 6 member m[ember] [group_name | organization_name [-a member_list] [-r member_list] ] Edits the membership list for a group or organization. If you do not specify a group or organization, the member subcommand prompts you for names to add or remove. To add names or aliases to a membership list, use the -a option followed by the names separated by commas. To delete names from a membership list, use the -r option followed by the names separated by commas. If you do not include either the -a or -r option on the command line, rgy_edit prompts you for names to add or remove. Removing names from the membership list for a group or organization has the side effect of deleting the login account for removed member (and, of course, eliminating any permissions granted as a result of the membership the next time the member's ticket-granting ticket is renewed). 6 delete del[ete] name Deletes a registry entry. If you delete a principal, rgy_edit deletes the principal's account.If you delete a group or organization, rgy_edit deletes any accounts associated with the group or organization. You cannot delete reserved principals. 6 adopt adopt uuid principal_name [-u unix_number] [ -f fullname] [-q quota] adopt uuid group_name [-f fullname] [-nl] adopt uuid organization_name [-f fullname] Creates a principal, group, or organization for the specified UUID. The principal, group, or organization is created to adopt an orphan object. Orphans are registry objects that cannot be accessed because 1) they are owned by UUIDs that are not associated with a principal or group and 2) no other principal, group, or organiza- tion has access rights to the orphaned object. UUIDs are associ- ated with all registry objects when the object is created. When the registry object is deleted, the association between the object and the UUID is also deleted. The principal_name, group_name, or organization_name you specify must be unique in the registry as it must be when you create a principal, group, or organization using the add subcommand. Except for the manner in which it is created, the principal, group, or organization created by the adopt subcommand is no different from any other principal, group, or organization. The uuid option specifies the UUID number to be assigned to the principal, group,or organization. The UUID supplied must be the one that owns the orphaned object. Specify the uuid in RPC print string format as 8 hexadecimal digits, a hyphen; 4 hexadecimal digits, a hyphen; 4 hexadecimal digits, a hyphen; 4 hexadecimal digits, a hyphen; and 12 hexadecimal digits. The format follows: nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn For cell principals only, the -u option specifies the UNIX number to be associated with the cell name. If you do not enter this option, the next sequential UNIX number is supplied as a default. For all principals other than cells, the UNIX number is extracted from information embedded in the principal's UUID and cannot be specified here. For principals, the -q option specifies the principal's object creation quota. If you do not enter the option, the object creation quota is set to "unlimited." For groups, the -nl option turns off the project list inclusion property so that groups are not included in project lists. If you do not enter this option, the group is included in project lists. For principals, groups, and organizations, the -f option supplies the object's fullname. If you do not enter the -f option, fullname defaults to blank. An error occurs if you specify a name or UNIX number that is already defined within the same domain of the database. Note that in the current implementation of the DCE, UNIX numbers are embedded in UUID numbers. If you try to create a group or organization to adopt an orphaned object and fail, it could be because the embedded UNIX number is invalid because it does not fall within the range of valid UNIX numbers set for the cell as a registry property. If this is the case, you must reset the range of valid UNIX numbers to include the UNIX number embedded in the UUID and then try again to adopt the object. 5 account_commands ACCOUNT SUBCOMMANDS 6 view v[iew] [pname [gname [oname]]] [-f] Displays login accounts. Without the -f option, view displays only the user fields in each account entry. These fields include each account's + Principal, group, and organization name + Encrypted password + Miscellaneous information + Home directory + Login shell With -f, view displays the full entry, including the adminis- trative fields as well as the user fields. Administrative information includes: + Who created the account + When the account was created + Who last changed the account + When the account was last changed + When the account expires + Whether the account is valid + Whether the account principal's password is valid + When the account principal's password was last changed 6 add a[dd] [pname [-g gname -o oname -mp password {-rp | -pw password} [-m misc] [-h homedir] [-s shell] [-pnv | -pv] [-x account_exp | none] [-anv | -av] [ [-ena[ble] option | -dis[able] option]...] [-gs date_and_time] [-mcr lifespan] [-mcl lifespan]]] Creates a login account. If you enter the subcommand only or the subcommand and the optional pname argument (principal name), rgy_edit prompts you for all information. If you enter the subcommand, the pname argument, and the gname (group name) argument or the the pname, gname and oname (organization name) arguments, you must also enter the -mp, and -pw or -rp options. All other options are optional. The pname argument specifies the principal for whom the account should be created. The -g and -o options specify the account's group and organization. If the principal specified in pname is not already a member of the specified group and organization, rgy_edit automatically attempts to add the principal to the membership lists. If you do not have the appropriate permissions for the group and organization, the attempt will fail and the account will not be created. The -rp option generates a random password for the account. The primary use of this option is to create passwords for accounts that will not be logged into (since the random password can never be supplied.) The -pw option is used to supply a password for the account on the command line. If you use the -rp option or the -pw option, you must also use the -mp option to supply your password so your identity can be validated. If you do not specify the -rp option or the -pw option, rgy_edit prompts for the account's password twice to ensure you did not make a typing mistake. Then it prompts for your password to verify your identity. If the user's password management policy allows the selection of generated passwords, specifying "*" as the argument to the -pw option or at the account's password prompt automatically generates a plaintext password. If the user's password management policy requires the selection of generated passwords, specifying the -pw option is an error. rgy_edit displays a generated password and then prompts for the password for confirmation. The format of password must adhere to the policy of the associated organization or the policy of the registry as a whole, whichever is more restrictive. The information supplied with the -m option is used to create the GECOS field for the account in the /etc/passwd file [on UNIX]. The -h option specifies the pathname of the principal's home directory. The default homedir is /. The -s option specifies the pathname of the principal's login shell. The default shell is a null string. The -pnv (password not valid) option specifies that the password has expired. Generally, users must change their passwords when the passwords expire. However, the policy to handle expired passwords and the mechanism by which users change their passwords are defined for each platform, usually through the login facility. The -pv option indicates the password is not expired (the default). The -x option sets an expiration date for the account in yy/mm/dd/hh/mm/ss format. The default is "none," meaning that the password will never expire. The -anv (account not valid) option specifies that the account is not currently valid for login. The -av option indicates the account is currently valid (the default). The -enable and -disable options set or clear the following options: + The c[lient] option, if enabled, allows the principal to act as a client and log in, acquire tickets, and be authenticated. If you disable client, the principal cannot act as a client. The default is enabled. + The s[erver] option, if enabled, allows the principal to act as a server and engage in authenticated communication. If you disable server, the principal cannot act as a server that engages in authenticated communication. The default is enabled. + The po[stdated] option, if enabled, allows tickets with a start time some time in the future to be issued to the account's principal. The default is disabled. + The f[orwardable] option, if enabled, allows a new ticket- granting ticket with a network address that differs from the present ticket-granting ticket address to be issued to the account's principal. The default is enabled. + The pr[oxiable] option, if enabled, allows a new ticket with a different network address than the present ticket to be issued to the account's principal. The default is disabled. + The T[GT_authentication] option, if enabled, specifies that tickets issued to the account's principal can use the ticket- granting-ticket authentication mechanism. The default is enabled. + The r[enewable] option turns on the Kerberos V5 renewable ticket feature. This feature is not currently used by the DCE; any use of this option is unsupported at the present time. + The dup[_session_key] option allows tickets issued to the account's principal to have duplicate keys. The default is disabled. The -gs (good since date) is the date and time the account was last known to be valid. When accounts are created, this date is set to the account creation time. If you change the good since date, any tickets issued before the changed date are invalid. Enter the date in yy/mm/dd.hh:mm format. The -mcr (maximum certificate renewable) option is the number of hours before a session with the principal's identity expires and the principal must log in again to reauthenticate. The default is 4 weeks. The -mcl (maximum certificate lifetime) option is the number of hours before the Authentication Service must renew a principal's service certificates. This is handled automatically and requires no action on the part of the principal. The default is 1 day. 6 change c[hange] [-p pname] [-g gname] [-o oname] [-np pname] [-ng gname] [-no oname] [{-rp | -pw password} -mp password] [-m misc] [-h homedir] [-s shell] [-pnv | -pv] [-x account_exp | none] [-anv | -av] [[-ena[ble] option | -dis[able] option]...] [-gs date_and_time] [-mcr lifespan] [-mcl lifespan] Changes an account. The -p, -g, and -o options identify the account to change. The -np, -ng, and -no options change the account's, principal, group, and organization, respectively. If you do not specify all three -p, -g, and -o options, wildcard updates can occur. For example, if you specify only the -g option, the changes affect all accounts that are associated with the named group. Note that you cannot use wildcarding to change passwords. To change a password, you must enter the -p, -g, and -o options. All other options have the same meaning as described in the add command for accounts. Note that the -rp option can be used to change the random passwords of the reserved accounts created by sec_create_db when the registry database is created. 6 delete del[ete] -p pname [-g gname] [-o oname] Deletes the specified account. Enter the -p option to delete the specified principal's account. Enter the -g or -o option to delete accounts associated with the specified group or organization. If you enter the -g or -o option, rgy_edit prompts individually for whether to delete each account associated with the group or organization. 6 cell ce[ll] cellname [-ul unix_num] [-uf unix_num] [-gl gname] [-ol oname] [-gf gname] [-of oname] [-mp passwd] [-fa name] [-fp passwd] [-q quota] [-x account_expiration_date | none] Creates a cross-cell authentication account in the local and foreign cells. This account allows local principals to access objects in the foreign cell as authenticated users and vice versa. The admin- istrator in the foreign cell must have also set up a standard account, whose ID and password the administrator of the foreign cell must supply to you. The cellname variable specifies the full pathname of the foreign cell with which you will establish the cross-cell authentication account. This name is stripped of the path qualifier and prefixed with "krbtgt." The resulting name is used as the primary name for the cross-cell authentication account. For example, if you enter /.../dresden.com, the principal name is krbtgt/dresden.com. The -ul option specifies the UNIX number for the local cell's principal. The -uf option specifies the UNIX number for the foreign cell's principal. If you do not specify these UNIX numbers, they are generated automatically. The -gl and -ol options specify the local account's group and organization. The -gf and -of options specify the foreign account's group and organization. The -mp option specifies the password of the person who invoked rgy_edit. The -fa option specifies the name identifying the account in the foreign cell, and the -fp option specifies the account's password. The -q option specifies the total number of objects that can be created in your cell's registry by all foreign users who use the cross-cell authentication account to access your cell. The object creation quota defaults to 0 (zero), meaning that principals in the foreign cell cannot create objects in the local cell. The object creation quota set for your cell's account in the foreign cell places the same restriction on the number of objects that your cell's principals can create in the foreign cell's registry. The -x option specifies the account expiration date for both the local and foreign accounts. The default for this option is "none." Note that the object creation quota for the local account defaults to 0 (zero), meaning that principals in the foreign cell cannot create objects in the local cell. You can change this with the rgy_edit change subcommand. 5 key_management_commands KEY MANAGEMENT SUBCOMMANDS The key management subcommands must be run in command-line mode. 6 ktadd kta[dd] -p principal_name [-pw password] [-a[uto]] [-r[egistry]] [-f key-file] Creates a password for a server or machine in the keytab file on the local node. The -p option specifies the name of the server or machine principal for which you are creating a password. The -pw option lets you supply the password on the command line. If you do not enter this option or the -auto option, ktadd prompts for the password. The -a option generates the password randomly. If you use this option, you must also use the -r option. If you do not specify the -auto or the -pw option, you are prompted for a password. The -r option updates the principal's password in the registry to match the string you enter (or automatically generate) for the password in the keytab file. Use it to ensure that the principal's password in the registry and the keytab file are in synch when you change a principal's password in the keytab file. To use this option, a password for the principal must exist in the default keytab file or the keytab file named by the -f option. The -f option specifies the name of the server keytab file on the local node to which you are adding the password. If you do not specify a keytab file name, dce$local:[krb5]v5srvtab.; is used. Note that you must be privileged to add entries in the default keytab file. 6 ktlist ktl[ist] [-p principal_name] [-f keyfile] Displays principal names and password version numbers in the local keytab file. The -p option specifies the name of the server or machine principal for which you are displaying passwords. The -f option specifies the name of the server keytab file on the local node for which you want to display entries. If you do not specify a keytab file name, dce$local:[krb5]v5srvtab.; is used. 6 ktdelete ktd[elete] -p principal_name -v version_number [-f keyfile] Deletes a sever or machine principal's password entry from a keytab file. The -p option specifies the name of the server or machine principal for whom you are deleting a password entry. The -v option specifies the version number of the password you want to delete. Version numbers are assigned to a principal's password whenever the principal's password is changed. This allows any servers or machines still using tickets granted under the old pass- word to run without interruption until the ticket expires naturally. The -f option specifies the name of the server keytab file on the local node from which you want to delete passwords. If you do not specify a keytab file name, dce$local:[krb5]v5srvtab.; is used. Note that you must be privileged to delete entries in the default keytab file. You must have the appropriate access rights to delete entries in other keytab files. 5 miscellaneous_commands Miscellaneous Commands 6 domain do[main] [p | g | o | a] Changes or displays the type of registry information being viewed or edited. You can specify p for principals, g for groups, o for organizations, or a for accounts. If you supply no argument, rgy_edit displays the current domain. 6 site si[te] [[name]] [-u[pdate]] Changes or displays the registry site being viewed or edited. The name variable is the fully qualified name of the cell that contains the registry to which you want access. If you supply no argument, rgy_edit displays the current site. The -update option indicates you want to talk to an update site in the specified cell. 6 properties prop[erties] Changes or displays registry properties. This command prompts you for changes. Press to leave information unchanged. 6 policy po[licy] [organization_name] [-al lifespan | forever] [-pl passwd_lifespan | forever] [-px passwd_exp_date | none] [-pm passwd_min_length] [-pa | -pna] [-ps | -pns] Changes or displays registry standard policy or the policy for an organization. Enter organization_name to display or change policy for that specific organization. If you do not enter organization_name the subcommand affects standard policy for the entire registry. The -al option determines the account's lifespan, the period during which accounts are valid. After this period of time passes, the accounts become invalid and must be recreated. An account's lifespan is also controlled by the add and change subcommands -x option. If the two lifespans conflict, the shorter one is used. Enter the lifespan in the following in the following format: weekswdaysdhourshminutesm For example, 4 weeks and 5 days is entered as 4w5d. If you enter only a number and no weeks, days, or hours designation, the designation defaults to hours. If you end the lifepan with a number and no weeks, days, or hours designation, the number with no designation defaults to seconds. For example, 12w30 is assumed to be 12 weeks thirty seconds. The -pl option determines the password lifespan, the period of time before account's password expires. Generally, users must change their passwords when the passwords expire. However, the policy to handle expired passwords and the mechanism by which users change their passwords are defined for each platform, usually through the login facility. Enter passwd_lifespan as a number indicating the number of days. If you define a password lifespan as forever, the password has an unlimited lifespan. The -px option specifies the password expiration date in yy/mm/dd/hh.mm:ss format. Generally, users must change their passwords when the passwords expire. However, the policy to handle expired passwords and the mechanism by which users change their passwords are defined for each platform, usually through the login facility. If you define a password expiration date as none, the password has an unlimited lifespan. The -pm, -ps, -pns, -pa, and -pna options all control the format of passwords as follows: + -pm - Specifies the minimum length of passwords in characters. If you enter 0, no password minimum length is in effect. + -ps and -pns - Specify whether passwords can contain all spaces (-ps) or can not be all spaces (-pns). + -pa and -pna - Specify whether passwords can consist of all alphanumeric characters (-pn) or must include some non- alphanumeric characters (-pna). 6 auth_policy au[th_policy] Changes and/or displays registry authentication policies. This command prompts you for changes. Press to leave information unchanged. 6 defaults def[aults] Changes or displays the home directory, login shell, password valid option, account expiration date, and account valid option default values that rgy_edit uses. This command first displays the current defaults. It then prompts you for whether or not you want to make changes. If you make changes, defaults immediately changes the defaults for the current session, and it saves the new defaults in sys$login:.rgy_editrc. The newly saved defaults are used until you change them. 6 help h[elp] [command Displays usage information for rgy_edit. If you do not specify a particular command, rgy_edit lists the available commands. 6 quit q[uit] Exit rgy_edit. 6 exit e[xit] Exit rgy_edit. 6 login l[ogin] Lets you establish a new network identity for use during the rgy_edit session. The rgy_edit login command prompts for a principal name and password. 6 scope sc[ope] [name] Limits the scope of the information displayed by the view subcommand to the directory (specified by name) in the registry database. 5 local_registry_commands Commands for the Local Registry To edit or view the local registry, invoke rgy_edit with the -l option while you are logged into the machine whose local registry you want to maintain. This section lists the commands that are valid for editing or viewing the local registry. When you invoke rgy_edit with the -l option, only the subcommands and options listed here can be used. 6 view v[iew] Displays local registry entries. 6 delete del[ete] principal_name Deletes the account and credential information for principal_name from the local registry. 6 purge pu[rge] Purges expired local registry entries. This command has no options or arguments. The time limit, or lifespan, for which an entry in the local registry is valid is set as a property of the local registry with the properties subcommand. When the purge subcommand is run, it deletes all expired entries. The lifespan begins when an entry for the principal is added to the local registry (that is, the beginning of the lifespan is the last time the principal logged in to the local machine.) The lifespan ends after the time limit set as a local registry property. 6 properties pr[operties] Changes and/or displays local registry properties and policies. This command displays the current properties and then prompts for whether you want to make changes to them. You can change the local registry's: + Capacity - A number representing the total number of entries the local registry can contain at any one time. When the capacity is reached, subsequent new entries overwrite the oldest entries. + Account lifespan - The time in which an account in the local registry is valid in the following format: weekswdaysdhourshminutesm For example, 4 weeks and 5 days is entered as 4w5d. If you enter only a number and no weeks, days, or hours designation, the designation defaults to hours. If you end the lifepan with a number and no weeks, days, or hours designation, the number with no designation defaults to seconds. For example, 12w30 is assumed to be 12 weeks thirty seconds. 4 secd NAME secd - The DCE Security Server SYNOPSIS secd [-b[ootstrap]] [-lockpw] [-locksm[ith]] [pname] [-rem[ote]] [-master_seqno new_master_seqno] [-cpi time] [-restore_master] [-v[erbose]] OPTIONS -locksm[ith] Restarts the master Security Server in locksmith mode. Use this mode if you cannot access the registry as the principal with full registry access, because that principal's account has been inadvertently deleted or its password lost. -pname The pname argument is the name of the locksmith principal. If no registry account exists for this principal, secd creates one. -lockpw Prompt for a new locksmith password when running in locksmith mode. This option allows you to specify a new password for the locksmith account when the old one is unknown. -rem[ote] Allows the locksmith principal to log in remotely. If this option is not used, the principal must log in from the local machine on which secd will be started. -bo[otstrap] Always waits only one minute between tries to export binding information to the Cell Directory Service during DCE config- uration. If you do not specify this option, during initial- ization secd sleeps for 1 minute if CDS is not available when it tries to export binding information. If the export fails a second time, it sleeps for 2 minutes before it tries again. If it still fails, it sleeps for 4, 8, and 16 minutes between retries. Then, sleep time stays at 16 minutes until the binding export succeeds. -master_seqno Sets a new master sequence number for the master replica. This option is used only in unusual situations when a replica that you want to be the master has a master sequence number that is lower than (or equal to) another master sequence number in the system. When the master detects that its master sequence number is lower than another one in the system, it marks itself as a duplicate master and its process exits. Each time you start the master replica, it will notice that it has been deemed a duplicate master, and its process will again exit. Use this option to assign a new master sequence number to the replica you want to be master. The new sequence number should be one digit higher than the highest master sequence number in the system. (Use the dcecp registry show -replica command for each replica to find the highest master sequence number.) -cpi The checkpoint interval for the mater registry database. This is the interval in seconds at which the master will read its database to disk. The default is one hour. -restore_master Marks all slave replicas for initialization during the master restart. Use this option only to recover from a catastrophic failure of the master security server (for example, if the database is corrupted and then restored from a backup tape). -v[erbose]] Runs in verbose mode. All options start the Security Server on the local node. DESCRIPTION The secd daemon is the Security Server. It manages all access to the registry database. You must have root privileges to invoke the secd. The Security Server can be replicated, so that several copies of the registry database exist on a network, each managed by a secd process. Only one Security Server, the master replica, can perform database update operations (such as adding an account). Other servers, the slave replicas, can perform only lookup operations (such as validating a login attempt). A DCE Host daemon (dced) must be running on the local node when secd is started. Typically, dced and secd are started at boot time. The secd server places itself in the background when it is ready to service requests. LOCKSMITH MODE The secd -locksmith option starts secd in locksmith mode. The -locksmith option can be used only with the master replica. In locksmith mode, the principal name you specify to secd with pname becomes the locksmith principal. As the locksmith principal, you can repair malicious or accidental changes that prevent you from logging in with full registry access privileges. If no account exists for pname, secd establishes one and prompts you for the account's password. (Use this password when you log in to the account as the locksmith principal.) If an account for pname exists, secd changes the account and policy information as described in the tables titled "Locksmith Account Changes Made by the Security Server" and "Registry Policy Changes Made by the Security Server." These changes ensure that even if account or registry policy was tampered with, you will now be able to log in to the locksmith account. In locksmith mode, all principals with valid accounts can log in and operate on the registry with normal access checking. The locksmith principal, however, is granted special access to the registry: no access checking is performed for the authenticated locksmith principal. This means that, as the locksmith principal, you can operate on the registry with full access. The following table shows locksmith account changes that can be made by the security server. IF THE SECURITY SERVER FINDS IT CHANGES ======================================================================== Password-Valid flag is set to no Password-Valid flag to yes ________________________________________________________________________ Account Expiration date is set to Account Expiration date to less than the current time plus one the current time plus one hour hour ________________________________________________________________________ Client flag is set to no Client flag to yes ________________________________________________________________________ Account-Valid flag is set to no Account-Valid flag to yes ________________________________________________________________________ Good Since date is set to greater Good Since date to the than the current time current time ________________________________________________________________________ Password Expiration date is set Password Expiration date to less than current time plus to the current time plus one hour one hour ------------------------------------------------------------------------ The following table shows registry policy changes that can be made by the security server. IF THE SECURITY SERVER FINDS IT CHANGES ======================================================== Account Lifespan is set to Account Lifespan to the less than the difference current time plus one hour between the locksmith minus the locksmith account creation date and account creation date the current time plus one hour _________________________________________________________ Password Expiration date is Password Expiration date set to greater than the time to the current time plus the password was last one hour changed but less than the current time plus one hour Use the -lockpw option if the locksmith account exists but you do not know its password. This option causes secd to prompt for a new lock- smith password and replace the existing password with the one entered. Use the -remote option to allow the locksmith principal to log in from a remote machine. The secd program normally runs in the background. When you start secd in locksmith mode, it runs in the foreground so that you can answer prompts. EXAMPLES All of the commands shown in the following examples must be run by a privileged process: 1. Start a Security Server after you create the database with sec_create_db. $ run sys$system:dce$secd 2. Restart an existing replica (master or slave). $ run sys$system:dce$secd 3. Start the Security Server in locksmith mode and allow the master_admin principal to log in on a remote machine. $ secd :== $sys$system:dce$secd.exe $ secd -locksmith master_admin -remote 4 sec_admin NAME sec_admin - Registry replica administration tool SYNOPSIS sec_admin [-site name] [-nq] OPTIONS -site name The -site option causes sec_admin to bind to the replica specified by the name argument. If the option is not supplied, sec_admin binds randomly to any replica in the local cell. The name argument can be: + A specific cell_name (or /.: for the local cell) to bind to any replica in the named cell. + The global name of a replica to bind to that specific replica in that specific cell. + The name of a replica as it appears on the replica list to bind to that replica in the local cell. + A string binding to a specific replica. An example of a string binding is ncadg_ip_udp:15.22.144.163. This form is used primarily for debugging or if the Cell Directory Service is not available. -nq The -nq flag turns off queries initiated by certain sec_admin subcommands before they perform a specified operation. For example the delrep subcommand deletes a registry replica. Before sec_admin performs the deletion, it prompts for verifi- cation. If you invoke sec_admin with the -nq option, the subcommand performs the deletion without prompting. NOTES With the exception of the following subcommands, this command is replaced at Revision 1.1 by the dcecp command. This command may be fully replaced by the dcecp command in a future release of DCE, and may no longer be supported at that time. + monitor + exit + help + quit DESCRIPTION The registry database is replicated: each instance of a registry server, secd, maintains a working copy of the database in virtual memory and on disk. One server, called the master replica, accepts updates and handles the subsequent propagation of changes to all other replicas. All other replicas are slave replicas, which accept only queries. Each cell has one master replica and numerous slave replicas. Using the sec_admin command you can: + View a list of replicas + Delete a replica + Reinitialize a replica + Stop a replica + Put the master replica into and out of the maintenance state + Generate a new master key used to encrypt principal keys + Turn the master registry into a slave registry and a slave registry into the master registry.. Note that sec_admin cannot add, delete, or modify information in the database, such as names and accounts. Use rgy_edit to modify registry database entries. THE DEFAULT REPLICA AND DEFAULT CELL Most sec_admin commands are directed to a default replica. When sec_admin is invoked, it automatically binds to a replica in the local cell. This replica becomes the default replica. Identifying the Default Replica and the Default Cell You use the site subcommand to change the default replica and, optionally, the default cell. When you use the site command, you can supply the name of a specific replica, or you can simply supply the name of a cell. If you supply a cell name, sec_admin binds to a replica in that cell randomly. If you supply a specific replica name, sec_admin binds to that replica. Specifically, you can supply any of the following names to the site subcommand: + A cell name. If you enter a cell name, the named cell becomes the default cell. The sec_admin command randomly chooses a replica to bind to in the named cell, and that replica becomes the default replica. + The global name given to the replica when it was created. A global name identifies a specific replica in a specific cell. That cell becomes the default cell and that replica the default replica. + The replica's name as it appears on the replica list (a list main- tained by each Security Server containing the network addresses of each replica in the local cell). That replica becomes the default replica and the cell in which the replica exists becomes the default cell. + The network address of the host on which the replica is running. The replica on that host becomes the default replica, and the cell in which the host exists becomes the default cell. Naming the Default Replica As an example, assume a replica named subsys/dce/sec/rs_server_250_2: + Exists in the local cell /.../dresden.com + Has a global name of /.../dresden.com/subsys/dce/sec/rs_server_250_2 + Is named subsys/dce/sec/rs_server_250_2 on the replica list + Runs on a host whose ip network address is 15.22.144.248 This replica can then be identified to the site subcommand in any of the following ways: + /.../dresden.com/subsys/dce/sec/rs_server_250_2 - The replica's full global name. + subsys/dce/sec/rs_server_250_2 - The replica's cell-relative name on the replica list. + ncadg_ip_udp:15.22.144.248 - The network address of the host on which the replica runs. Naming the Default Cell When a default replica is identified specifically, its cell becomes the default cell. In the example in "Naming the Default Replica" above, the default cell is /.../dresden.com. You can specify simply a cell name to the site subcommand. When this is done, any replica in that cell is selected as the default replica. For example, assume /.../bayreuth.com/subsys/dce/sec/rs_server_300_1 and /.../bayreuth.com/subsys/dce/sec/rs_server_300_2 are replicas in the cell /.../bayreuth.com. If you type site /.../bayreuth.com then /.../bayreuth.com becomes the default cell and either /.../bayreuth.com/subsys/dce/sec/rs_server_300_1 or /.../bayreuth.com/subsys/dce/sec/rs_server_300_2 becomes the default replica. AUTOMATIC BINDING TO THE MASTER Some of the sec_admin subcommands can act only on the master registry and thus require binding to the master registry. If you execute a sub- command that acts only on the master and the master is not the default replica, sec_admin attempts to bind to the master replica in the current default cell automatically. If this attempt is successful, sec_admin displays a warning message informing you that the default replica has been changed to the master registry. The master registry will then remain the default replica until you change it with the site subcommand. If the attempt to bind is not successful, sec_admin displays an error message, and the subcommand fails. INVOKING sec_admin When you invoke sec_admin, it displays the current default replica's full global name and the cell in which the replica exists. Then it displays the sec_admin> prompt. $ sec_admin Default replica: /.../dresden.com/subsys/dce/sec/music Default cell: /.../dresden.com sec_admin> At the sec_admin> prompt, you can enter any of the sec_admin subcommands. SUBCOMMANDS The subcommand descriptions that follow use default_replica to indicate the default replica and other_replica to indicate a replica other than the default. other_replica must identify a replica in the default cell. It is specified by its name on the cell's replica list (that is, by its cell-relative name). Use the lrep subcommand to view the default cell's replica list. become [ -master ] [ -slave ] The -master option makes the current default replica (which must be a slave) the master replica. The -slave option makes the current default replica (which must be the master) a slave replica. This method of changing to master or slave can cause updates to be lost. The change_master subcommand is the preferred means of designating a different master replica. However, you may find the become -master command useful if the master server is irrevocably damaged and you are unable to use change_master. change_master -to other_replica Make the replica specified by other_replica the master replica. To perform this operation, other_replica must be a slave, and the current default replica must be the master. If the current default replica is not the master, sec_admin attempts to bind to the master. If the change operation is successful, the current master: 1. Applies all updates to other_replica 2. Becomes a slave 3. Tells other_replica to become the master delr[ep] other_replica [-force ] Delete the registry replica identified by other_replica. To perform this operation, the current default replica must be the master. If it is not, sec_admin attempts to bind to the master. If the delete operation is successful, the master: 1. Marks other_replica as deleted 2. Propagates the deletion to all replicas on its replica list 3. Delivers the delete request to other_replica 4. Removes other_replica from its replica list The -force option causes a more drastic deletion. It causes the master to first delete other_replica from its replica list and then to propagate the deletion to the replicas that remain on its list. Since this operation never communicates with the deleted replica, you should use -force only when the replica has died irrecoverably. If you use -force while other_replica is still running, you should then use the destroy subcommand to eliminate the deleted replica. h[elp] [command] Lists the sec_admin subcommands and shows their allowed abbreviations. If command is specified, displays help for the specified command. info [-full] Displays status information about the default replica. The info subcommand contacts the default replica to obtain the appropriate information. If this information is not available, info prints the replica name and a message stating the information is not available. Without the -full option, info displays: + The default replica's name and the name of the cell in which the replica exists + Whether the replica is a master or a slave + The date and time the replica was last updated and the update sequence number + An indication of the replica's state, as follows: - Bad State - The state of the replica prohibits the requested operation. - Uninitialized - The database is a stub database that has not been initialized by the master replica or another up-to-date replica - Initializing - The replica is in the process of being initialized by the master replica or another up-to-date replica - In Service - The replica is available for queries and propagation updates if it is a slave replica or queries and updates if it is the master replica - Copying Database - The replica is in the process of initializing (copying its database to) another replica - Saving Database - The replica is in the process of saving its database to disk. - In Maintenance - The replica is unavailable for updates but will accept queries - Changing Master Key - The replica is in the process of having its master key changed - Becoming Master- The replica is in the process of becoming the master replica (applicable to slave replicas only) - Becoming Slave- The master replica is in the process of becoming a slave replica (applicable to the master replicas only) - Closed - The replica is in the process of stopping - Deleted - The replica is in the process of deleting itself - Duplicate Master - The replica a duplicate master and should be deleted. The master replica is available for queries when it is in the in-service, copying-database, in-maintenance, master-key- changing and becoming-slave states. It is available for updates only when it is in the in-service state. A slave replica is available for queries when it is in the in- service, copying-database, master-key-changing and becoming- master states. It accepts updates from the master replica only when it is in the in-service state. It accepts a request from the master replica to initialize only when it is in the uninitialized or in-service state. The -full option displays all the above information and the following information: + The default replica's unique identifier + The replica's network addresses + The unique identifier of the cell's master replica + The network addresses of the cell's master replica + The master sequence number, which is the sequence number of the event that made the replica the master + If the replica is the master replica, the update sequence numbers that are still in the propagation queue and have yet to be propagated + The DCE software version number. initr[ep] other_replica Reinitializes a replica by copying an up-to-date database to other_replica. The master replica initiates and guides the operation. If th operation is successful 1. The master replica a. Marks other_replica for reinitialization b. Tells other_replica to reinitialize itself c. Gives other_replica a list of replicas with up-to-date databases 2. The other_replica picks a replica from the list and asks that replica to initialize it (that is, to copy its database to other_replica) To perform this operation, other_replica must be a slave, and the current default replica must be the master. If the current default replica is not the master, sec_admin attempts to bind to the master. This subcommand is generally not used under normal conditions. lr[ep] [-s[tate]] [-u[uid]] [-a[ddr]] [-p[rop]] [-al[l]] Lists the replicas on the default replica's replica list. If you enter no options, the display includes the replica name and whether or not it is the master replica. In addition if the master replica's list is being displayed, slave replicas marked for deletion are noted. With options, the display includes this information and the information described in the following paragraphs. The -state option shows each replica's current state, the date and time the replica was last updated, and the update sequence number. To obtain this information, lrep contacts each replica. If this information is not available from the replica, lrep prints the replica name and a message stating the information is not available. The -addr option shows each replica's network addresses. The -uuid option shows each replica's unique identifier. The -prop option shows: + The date and time of the last update the master sent to each slave replica + The sequence number of the last update to each slave replica + The number of updates not yet applied to each slave replica + The status of the master replica's last communication with each slave replica + The propagation state of each slave replica. This state, illustrates how the master replica views the slave replica, can be any of the following: - Bad State-The state of the replica prohibits the requested operation. - Marked for Initialization-The replica has been marked for deletion by the master replica. - Initialized-The replica has been marked for initializa- tion by the master replica. - Initializing-The replica is in the process of being ini- tialized by the master replica. - Ready for Updates-The replica has been initialized by the master replica and in now available for propagation updates from the master replica. - Marked for Deletion-The replica has been marked for deletion by the master replica. This information is obtained from the master replica; the slave replicas are not contacted for this information. The -prop option is valid only for the master. For slave replicas, the -all option shows all the information above except that displayed by the -prop option. For the master replica, the -all option shows all the information. mas[ter_key] Generates a new master key for the default replica and re- encrypts account keys using the new key. The new master key is randomly generated. Each replica (master and slaves) maintains its own master key used to access the data in its copy of the database. monitor [-r m] Periodically list the registry replicas stored in the current default replica's replica list. The list includes each replica's current state, the date and time the replica was last updated and the update sequence number. Note that this is the same information as that displayed by the info sub- command with no options. The monitor subcommand contacts each replica to obtain the information it displays. If this information is not available from the replica, monitor prints the replica name and a message stating the information is not available. The -r option causes the replicas to be listed at intervals you specify. m is a number of minutes between intervals. The default is 15 minutes. destroy default_replica Destroy the current default replica. To perform this operation, the current default replica and the default replica you name as default_replica must be the same. This is to confirm your desire to perform the deletion. If the operation is successful, the default replica deletes its copy of the registry database and stops running. This subcommand does not delete default_replica from the replica lists. Use the delrep -force subcommand to delete the replica from the other replica lists. The preferred way to delete replicas is to use the delrep subcommand. However, the destroy subcommand can be used if delrep is unusable because the master is unreachable or the replica is not on the master's replica list. site [name [-u[pdate]]] Set or display the default cell and the default replica. The name argument identifies the replica to set as the default replica and, as a consequence, the default cell. It can be: + A specific cell_name (or /.: for the local cell) to make any replica in the named cell the default. + The global name of a replica to make the specified replica in the specified cell the default. + The name of a replica as it appears on the replica list to make the named replica (which exists in the default cell) the default replica. + A string binding to a specific replica. An example of a string binding is ncadg_ip_udp:15.22.144.163. This form is used primarily for debugging or if the Cell Directory Service is not available. The -u option specifies that sec_admin should find the master replica. Normally you specify the name of a cell for name in conjunction with the -u option. In this case sec_admin finds the master replica in that cell. If you use a replica name for name, sec_admin queries the named replica to find the master replica in the named replica's cell. If you supply no arguments, sec_admin displays the current default replica and default cell. stop Stops the Security Server (secd) associated with the default replica. sta[te] -maintenance | -service Puts the master replica into maintenance state or takes it out of maintenance state. This subcommand is useful for performing backups of the registry database. If the current default replica is not the master, sec_admin attempts to bind to the master. The -maintenance flag causes the master replica to save its database to disk and refuse any updates. The -service flag causes the master replica to return to its normal "in service" state and start accepting updates. e[xit] or q[uit] The quit and exit subcommands end the sec_admin session. EXAMPLES 1. The following example, invokes sec_admin and uses the lrep sub- command to list replicas on the replica list and their states: $ r sys$system:dce$sec_admin Default replica: /.../dresden.com/subsys/dce/sec/rs_server_250_ Default cell: /.../dresden.com sec_admin> lrep -st Replicas in cell /.../dresden.com (master) subsys/dce/sec/master state: in service Last update received at: 1993/11/16.12:46:59 Last update's seqno: 0.3bc subsys/dce/sec/rs_server_250_2 state: in service Last update received at: 1993/11/16.12:46:59 Last update's seqno: 0.3bc subsys/dce/sec/rs_server_250_3 state: in service Last update received at: 1993/11/16.12:46:59 Last update's seqno: 0.3bc sec_admin> 2. The following example, sets the default replica to the master in the local cell: sec_admin> site /.: -u Default replica: /.../dresden.com/subsys/dce/sec/master Default cell: /.../dresden.com sec_admin> 4 sec_create_db NAME sec_create_db - registry database creation utility SYNOPSIS sec_create_db {-master | -slave} -my[name] my_server_name [-cr[eator] creator_name] [-cu[nix_id] creator_unix_id] [-g[roup_low_id] g_unix_id] [-k[eyseed] keyseed] [-ma[x_unix_id] max_unix_id] [-o[rg_low_unix_id] o_unix_id] [-pa[ssword] default_password] [-p[erson_low_unix_id] p_unix_id] [-u[uid cell_uuid] [-v[erbose]] OPTIONS {-master | -slave} Specifies whether the database for the master replica should be created (-master) or a database for a slave replica should be created (-slave). All other sec_create_db options can be used with the -master option. Only the -myname, -keyseed, and -verbose options can be used with the -slave option. -my[name] Specifies the name that will be used by the Directory Service to locate the machine on which the cell's Security Server is running. -cr[eator] Specifies the principal name of the initial privileged user of the registry database (known as the "registry creator"). -cu[nix_id] Specifies the UNIX ID of the initial privileged user of the registry database. If you do not enter the UNIX ID, it is assigned dynamically. -g[roup_low_unix_id] Specifies the starting point for UNIX IDs automatically generated by the Security Service when groups are added with the rgy_edit command. k[eyseed] Specifies a character string used to seed the random key generator in order to create the master key for the database you are creating. It should be string that cannot be easily guessed. The master key is used to encrypt all account pass- words. Each instance of a replica (master or slave) has its own master key. You can change the master key using the sec_admin command. ma[x] Specifies the highest UNIX ID that can be assigned to a principal, group, or organization. -o[rg_low_unix_id] Specifies the starting point for UNIX IDs automatically generated by the Security Service when organizations are added with the rgy_edit command. -pa[ssword] The default password assigned to the accounts created by sec_create_db, including the account for the registry creator. If you do not specify a default password, -dce- is used. (Note that the hosts/local_host/self none none, krbtgt/cell_name none none, and nobody none none accounts are not assigned the default password, but instead a randomly generated password.) -p[erson_low_unix_id] Specifies the starting point for UNIX IDs automatically generated by the Security Service when principals are added with the rgy_edit command. -u[uid] Specifies the cell's UUID. If you do not enter this UUID, it is assigned dynamically. -v[erbose] Specifies that sec_create_db runs in verbose mode and displays all activity. DESCRIPTION The sec_create_db tool creates new master and slave databases in DCE$LOCAL:[VAR.SECURITY.RGY_DATA] on the machine from which sec_create_db is run. Normally, these databases are created only once by the system configuration tool, dce_config. However, you can use sec_create_db if you need to re-create the master or a slave database from scratch. You must be privileged to invoke sec_create_db. The sec_create_db -master option creates the master database on the machine on which it is run. This database is initialized with names and accounts, some of them reserved. You must use the rgy_edit command to populate the database with objects and accounts. When the master registry database is created, default ACL entries for registry objects are also created. These entries give the most privileged permission set to the principal named in the -cr[eator] option. If the principal is not one of the reserved names and accounts, sec_create_db adds it as a new principal and adds an account for that new principal. If the -cr option is not used, DCE$SERVER is the creator. The sec_create_db -slave option creates a slave database on the machine on which it is run. This command creates a stub database on the local node in DCE$LOCAL:[VAR.SECURITY.RGY_DATA] and adds the newly created replica to the master's replica list. The master then marks the replica to be initialized when a Security Server is started on the slave's node. The sec_create_db command also creates a registry configuration file, named DCE$LOCAL:[ETC.SECURITY]PE_SITE.;, that contains the network address of the machine on which the database is created. This file supplies the binding address of the secd master server if the Naming Service is not available. FILES DCE$LOCAL:[ETC.SECURITY]PE_SITE.; The file containing the network address of the machine on which the security database is created. DCE$LOCAL:[VAR.SECURITY.RGY_DATA] The directory in which the registry database files are stored. 4 sec_salvage_db NAME sec_salvage_db - Recover a corrupted registry database. The sec_salvage_db -check and -fix options are not currently available. SYNOPSIS sec_salvage_db -print [-dbpath db_pathname] [-prtpath print_pathname] [print_options] [-verbose] sec_salvage_db -reconstruct [-dbpath db_pathname] [-prtpath print_pathname] [reconstruct_options] [-verbose] sec_salvage_db -check [-dbpath db_pathname] [db_options] [-verbose] sec_salvage_db -fix [-dbpath db_pathname] [db_options] [-force] [-verbose] OPTIONS -check Check the database elements specified by db_options for incon- sistencies. This option sends a list to standard output of all bad list links, internal id references, and database keys and any detectable data inconsistencies. The -check option does not check fields for legal values. db_options Specify the database elements to be acted on by the -check or -fix options. If no db_options are specified, all are selected. The db_options are + -princ - Principals + -group - Groups + -org - Organizations + -acct - Accounts + -acl - ACLs + -policy - Policy + -state - Database State + -replicas - Replicas The .mkey.prt file and the princ.prt file contain unencrypted authentication keys. Ensure that only the privileged account can access these files and that they are never transferred over a network for viewing or backup. -fix Check the database for inconsistencies and prompt for whether to fix each inconsistency. After all inconsistencies have been processed, the option prompts for whether to save all fixes. -force Check the database for inconsistencies and fix each one with- out prompting. After all inconsistencies have been processed, the option prompts for whether to save all fixes. This option is valid only when used with the -fix option. -print Create files containing ASCII-formatted database records. These files are used by the -reconstruct option as a source for recreating the database. You can also manually edit the files to change information or fix problems. A separate file is created for each of the print_options specified. By default the -print option stores the master key file in the current directory and the database files in the rgy_print directory in the current directory. The -prtpath option lets you specify a different directory. print_options Specify the database elements to be acted on by the -print option. If the files exist, they are overwritten. If no print_options are specified, all are selected. The print_options and the files they create are + -princ - Put principal records in the file princ.prt and master key information in the file .mkey.prt. + -group - Put group records in the file group.prt. + -org - Put organization records in the file org.prt. + -policy - Put policy records in the file policy.prtt. + -state - Put information about the state of the database in the file rgy_state.prt. + -replicas - Put replica information in the file replicas.prt. -reconstruct Reconstruct the registry database from the ASCII-formatted print files created by the -print option. The reconstruct_options specify the print files to use. Specifies which elements of the registry database to re- construct. If no reconstruct_options are specified, all are selected. The reconstruct_options are + -pgo - Use data in the princ.prt, group.prt, org.prt, and .mkey.prt files to reconstruct: - Principals, groups, organizations - Principal's accounts - ACL's on database objects - The master key file + -policy - Use data from the policy.prt file to re- construct registry policies. + -state - Use data from the rgy_state.prt file to re- construct information about the state of the database. + -replicas - Use data from the replicas.prt file to reconstruct the master replica list. -dbpath db_pathname For the -print and -check options, -dbpath specifies the directory in which the registry database and the master key file are located. For the -reconstruct and -fix options, -dbpath specifies the directory in which to store the re- constructed or salvaged database. The -print and -check options expects to find the master key file, .mkey, in the directory above the directory that holds the database files. For example, if db_pathname is DCE$LOCAL:[VAR.SECURITY.NEW_RGY], the options look for the master key file in DCE$LOCAL:[VAR.SECURITY] and the database files in DCE$LOCAL:[VAR.SECURITY.NEW_RGY]. If this option is not specified, the default pathname is DCE$LOCAL:[VAR.SECURITY.RGY_DATA]. db_pathname can be a global pathname or a cell-relative name. -prtpath print_pathname For the print and -reconstruct options only, -prtpath specifies the directory in which to create (-print) the print files, or find (-reconstruct) the print files from which to reconstruct the database. By default the -print option creates and the -reconstruct option looks for the master key file in the current directory and the database files in the rgy_print subdirectory of the current directory. The -prtpath option lets you specify the directory that should be used instead of the current directory. For example, if you specify print_pathname as DCE$LOCAL:[VAR.SECURITY.REGISTRY], the master key print file will be created in that directory and the database print files in DCE$LOCAL:[VAR.SECURITY.REGISTRY.RGY_PRINT]. If any or all of the print files exist in print_pathname or the default directory, their contents are overwritten. print_pathname can be a global pathname or a cell-relative name. DESCRIPTION The sec_salvage_db tool is an aid to database administration and troub- leshooting. Although day-to-day administration is handled by the rgy_edit command, sec_salvage_db can be useful for listing registry data, reconstructing databases, and salvaging corrupted databases. The sec_salvage_db command supports two methods of operation: the check and fix method and the print and reconstruct method. These methods can be used in tandem. CHECK AND FIX METHOD The -check and -fix options are not currently available. The check and fix method recovers data from a corrupted database, fixing corrupted data links, data retrieval keys, and other internal references. You can use it on a database so corrupted that it prevents the Security Server (secd) from running or registry clients from operating correctly. The check and fix method repairs the database structure so that secd can run. (Note that data may be lost if corrupted pointers in the registry data files irreversibly sever the links between records.) The check and fix method uses the sec_salvage_db -check, -fix, and -force options. The -check option accesses each record in the database and reports all errors, but makes no fixes. Although you can run it to see the state of the database before you run the -fix option, it is not required to be run. The -fix option also accesses each record in the database and reports all errors, but as it finds each error, it prompts for whether or not to fix the error. When processing is complete, sec_salvage_db prompts for whether or not to save the changes. The -force option can only be used with the -fix option. If you use it, sec_salvage_db does not prompt for confirmation before it fixes each error it finds. sec_salvage_db will still prompt for confirmation before it saves the changes. THE PRINT AND RECONSTRUCT METHOD The print and reconstruct method allows you to reconstruct a database. It first creates ASCII files, called print files, that contain all accessible data in the database. Then, it reads the data in these files to construct a new database. If you cannot start a Security Server on the database host machine, you cannot use the print and re- construct method, but must use the check and fix method. (Note that before you run sec_salvage_db with the -print and -reconstruct options, you must stop the Security Server.) In addition to reconstructing the database, the print and reconstruct method has other uses. You can use it to + Make changes to the database by manually editing the print files created by the -print option and then reconstructing them from the changed print files. This can be especially useful for changing many user passwords, which may be necessary if the master key file is corrupted. + Obtain a listing of database contents. + Copy databases between different platforms. To use the print and reconstruct method run sec_salvage_db first with the -print option and then with the -reconstruct option. The -print option creates the ASCII print files from the registry data- base files. These files can be reviewed and edited to correct faulty information, such as name-to-UNIX ID mismatches or missing data, or to update existing data. The -reconstruct option recreates the registry database files from the print files. Because the -print option creates files containing all data in the data- base and the -reconstruct option recreates the database based on these files, you can use this method to move a database to another machine or even another cell. For example, if you run sec_salvage_db -print on an uncorrupted database, you can then run sec_salvage_db -reconstruct and specify a pathname on a different machine for where the database should be created. EDITING THE PRINT FILES To edit the print files, your entries must be in the following format: field_name optional_white_space=optional_white_space value Although you can leave spaces between the field name, the equals sign, and the value, field names and values cannot contain white space. A sample org.prt file follows: Record_Number = 2 Object_Type = ORG Name = org/none UUID = 0000000C-D751-21CA-A002-08001E039D7D Unix_ID = 12 Is_Alias_Flag = false Is_Required_Flag = false Fullname = Member_Name = nobody Member_Name = root Member_Name = daemon Member_Name = uucp Member_Name = bin Member_Name = dce-ptgt Member_Name = dce-rgy Member_Name = krbtgt/abc.com Member_Name = hosts/zebra/self Obj_Acl_Def_Cell_Name = /.../abc.com Obj_Acl_Entry = unauthenticated:r-t----- Obj_Acl_Entry = user:root:rctDnfmM Obj_Acl_Entry = other_obj:r-t----- Obj_Acl_Entry = any_other:r-t----- To update existing entries, simply supply a new value. For example, to update a principal's full name, the entry in the princ.prt file is Fullname = fullname The fullname variable is the principal's full name. The princ.prt file contains the following entry that allows you to update a principal's password in plain text: Plaintext_Passwd = This field does not display the principal's password. To update the password, simply enter the new one in plain text after the equals sign. When the database is reconstructed, the password is encrypted and any keys derived from that password are regenerated and used to overwrite any existing encryption key entries. To specify a NULL value, delete the existing value. For example, to specify a NULL value for a fullname in the princ.prt file, the entry is Fullname = PRINT FILE FIELDS AND VALUES The following lists describe the fields in the princ.prt, group.prt, org.prt, .mkey.prt, policy.prt, rgy_state.prt, and replicas.prt files. In the lists, an * (asterisk) indicates a segment or field that can appear multiple times in succession; a + (plus sign) indicates that if a stored UUID does not map to a name required for the field, the UUID is displayed. THE PRINC.PRT FILE The fields in the princ.prt file follow: + For all records: Record_Number The sequential number of the record in the database. Object_Type An indication of the type of object: PRINC=principal, DIR=directory. Name Name of the object. UUID Unique Identifier of the object. + For principals: Unix_ID The principal's Unix ID. Is_Alias_Flag An indication of whether or not the principal name is an alias or a primary name: true=alias, false=primary. Is_Required_Flag An indication of whether or not the principal is reserved: true=principal is reserved and cannot be deleted, false=principal is not reserved. Quota The principal's object creation quota: a non- negative integer or unlimited. Fullname The principal's fullname: a text string. Member_Name* The names of the groups to which the principal belongs. Obj_Acl_Def_Cell_Name The default cell name of this principal's object ACL. Num_Acl_Entries The number of entries in the principals object ACL. Obj_Acl_Entry*+ The contents of the principal's object ACL. Acct_Group_Name The account's group name. Acct_Org_Name The account's organization name. Acct_Creator_Name The name of principal who created this account. Acct_Creation_Time The date and time the account was created in yyyy/mm/dd.hh:mm format. The first two digits of the year, the hours, and the minutes are optional. Acct_Changer_Name Name of principal who last changed the account. Acct_Change_Time The date and time the account was last changed in yyyy/mm/dd.hh:mm format. (The first two digits of the year, the hours and the minutes are optional.) Acct_Expire_Time The date and time the account expires or none for no expiration date. The date and time are in yyyy/mm/dd.hh:mm format. (The first two digits of the year, the hours and the minutes are optional.) Acct_Good_Since_Time The date and time the principal's account was last known to be in an uncompromised state in yyyy/mm/dd.hh:mm, format or no for current time and date. (The first two digits of the year, the hours and the minutes are optional.) Acct_Valid_For_Login_Flag An indication of whether or not the account can be logged into: true=account is valid for login, false=account cannot be logged into. Acct_Valid_As_Server_Flag Indicates whether or not the account is a server and can engage in authenticated communication: true=account is a server, false=account is not server. Acct_Valid_As_Client_Flag Indicates whether or not the account is a client and can log in, acquire tickets, and be authenticated: true=account is a client, false=account is not a client. Acct_Post_Dated_Cert_Ok_Flag Indicates whether or not tickets with a start time some time in the future can be issued to the account's principal: true=postdated tickets can be issued, false=postdated tickets cannot be issued. Acct_Forwardable_Cert_Ok_Flag Indicates whether or not a new ticket-granting ticket with a network address that differs from the present ticket-granting address can be issued to the account's principal: true=account can get forwardable certificates, false=account cannot. Acct_TGT_Auth_Cert_Ok_Flag Indicates whether or not tickets issued to the account's principal can use the ticket-granting- ticket authentication mechanism: true=tickets can use the ticket-granting-ticket authentication mechanism, false=they cannot. Acct_Renewable_Cert_Ok_Flag Indicates whether or not tickets issued to the principal's ticket-granting ticket to be renewed: true=tickets can be renewed, false=tickets cannot be renewed. Acct_Proxiable_Cert_Ok_Flag Indicates whether or not a new ticket with a different network address than the present ticket can be issued to the account's principal: true=such a ticket can be issued, false=such a ticket cannot be issued. Acct_Dup_Session_Key_Ok_Flag Indicates whether or not tickets issued to the account's principal can have duplicate keys: true=account can have duplicate session keys, false=account cannot. Unix_Key The account principal's encrypted UNIX password: ASCII string. Plaintext_Passwd Stores the principal's password in plain text. This field is provided to allow principal's passwords to be changed. When the princ.prt file is processed by the sec_salvage_db -reconstruct option, this pass- word is encrypted using UNIX system encryption. This encrypted password is then stored as the principal's encrypted UNIX password in the Unix_Key field. Home_Dir The account principal's home directory: text string. Shell The account principal's login shell: text string. Gecos The account's GECOS information: text string. Passwd_Valid_Flag Indicates whether or not the account principal's password is valid: true=password is valid, false=password not valid. Passwd_Change_Time The date and time the account principal's password was last changed in yyyy/mm/dd.hh:mm format or now for the current date and time. The first two digits of the year, the hours and the minutes are optional. Max_Certificate_Lifetime The number of hours before the Authentication Service must renew the account principal's service certificates: an integer indicating the time in hours or default-policy to use the registry default. Max_Renewable_Lifetime The number of hours before a session with the account principal's identity expires and the principal must log in again to reauthenticate: an integer indicating the time in hours or default-policy to use the registry default. Master_Key_Version The version of the master key used to encrypt the account principal's key. Num_Auth_Keys The number of the account principal's authentication keys. Auth_Key_Version* A list of the version numbers of the account principal's authentication key. The first version number on the list represents the current authenti- cation key. Auth_Key_Pepper* The pepper algorithm used for the account principal's key: a text string or blank to use the default pepper algorithm. Auth_Key_Len* The length in bytes of the account principal's authentication key. Auth_Key* The account principal's authentication key: hex string. Auth_Key_Expire_Time* The date and time the account principal's authenti- cation key expires or none for no expiration. Date and time are in yyyy/mm/dd.hh:mm format. (The first two digits of the year, the hours and the minutes are optional.) + For directories: Obj_Acl_Def_Cell_Name+ The default cell name of the directory's object ACL. Num_Acl_Entries The number of entries in the directory's object ACL. Obj_Acl_Entry*+ The contents of the directory's object ACL. Init_Obj_Acl_Def_Cell_Name+ The default cell name of the directory's initial object ACL. Num_Acl_Entries The number of entries in the directory's initial object ACL. Init_Obj_Acl_Entry*+ The contents of the directory's initial object ACL. Init_Cont_Acl_Def_Cell_Name+ The default cell name of the directory's initial container ACL. Num_Acl_Entries The number of entries in the directory's initial container ACL. Init_Cont_Acl_Entry*+ The contents of the directory's initial container ACL. THE GROUP.PRT FILE The fields in the group.prt file follow: + For all records: Record_Number The sequential number of the record in the database. Object_Type An indication of the type of object: GROUP=group, DIR=directory. Name Name of the object. UUID Unique Identifier of the object. + For groups: Unix_ID Unix ID of the group. Is_Alias_Flag An indication of whether or not the group name is an alias or a primary name: true=alias, false=primary. Is_Required_Flag An indication of whether or not the group is reserved: true=group is reserved and cannot be deleted, false=group is not reserved. Projlist_Ok_Flag An indication of whether or not the group can be included in project lists: true=group can be included on project lists, false=group cannot be included. Fullname The group's fullname: a text string. Member_Name* The names of the group's members. Obj_Acl_Def_Cell_Name+ The default cell name of this group's object ACL. Num_Acl_Entries The number of entries in the group's object ACL. Obj_Acl_Entry*: The contents of the group's object ACL. + For directories: Obj_Acl_Def_Cell_Name+ The default cell name of this directory's object ACL. Num_Acl_Entries The number of entries in the directory's object ACL. Obj_Acl_Entry* The contents of the directory's object ACL. Init_Obj_Acl_Def_Cell_Name+ The default cell name of the directory's initial object ACL. Num_Acl_Entries The number of entries in the directory's initial object ACL. Init_Obj_Acl_Entry*+ The contents of the directory's initial object ACL. Init_Cont_Acl_Def_Cell_Name+ The default cell name of the directory's initial container ACL. Num_Acl_Entries The number of entries in the directory's initial container ACL. Init_Cont_Acl_Entry*+ The contents of the directory's initial container ACL. THE ORG.PRT FILE The fields in the org.prt file follow: + For all records: Record_Number The sequential number of the record in the database. Object_Type An indication of the type of object: ORG=organization, DIR=directory. Name Name of the object. UUID Unique Identifier of the object. + For organizations: Unix_ID Unix ID of the organization. Is_Alias_Flag An indication of whether or not the organization is an alias or a primary name: true=alias, false=primary. Is_Required_Flag An indication of whether or not the organization is reserved: true=organization is reserved and cannot be deleted, false=organization is not reserved. Fullname The organization's fullname: a text string. Member_Name* The names of the organization's members. Obj_Acl_Def_Cell_Name The default cell name of this organization's object ACL. Num_Acl_Entries The number of entries in the organization's object ACL. Obj_Acl_Entry*+ The contents of the organization's object ACL. + For organizations with policy: Acct_Lifetime The period during which accounts for the organiza- tion are valid: a integer number representing days or forever. Passwd_Min_Len The minimum length of the organization's password: a non-negative integer. Passwd_Lifetime The span in days of the lifetime of the organiza- tion's password: an integer or forever. Passwd_Expire_Time The date and time the organization's password expires in yyyy/mm/dd.hh:mm format. (The first two digits of the year, the hours and the minutes are optional.) Passwd_All_Spaces_Ok An indication of whether or not the organization's password can consist of all spaces: true=can consist of spaces, false=cannot. Passwd_All_Alphanumeric_Ok An indication of whether or not the organization's password can consist of all alphanumeric characters: true=can be all alphanumeric, false=cannot. + For directories: Obj_Acl_Def_Cell_Name+ The default cell name of the directory's object ACL. Num_Acl_Entries The number of entries in the directory's object ACL. Obj_Acl_Entry*+ The contents of the directory's object ACL. Init_Obj_Acl_Def_Cell_Name+ The default cell name of the directory's initial object ACL. Num_Acl_Entries The number of entries in the directory's initial object ACL. Init_Obj_Acl_Entry*+ The contents of the directory's initial object ACL. Init_Cont_Acl_Def_Cell_Name+ The default cell name of the directory's initial container ACL. Num_Acl_Entries The number of entries in the directory's initial container ACL. Init_Cont_Acl_Entry*+ The contents of the directory's initial container ACL. THE .MKEY.PRT FILE The fields in the .mkey.prt file follow: Master_Key_Version The integer version of the master key. Master_Key_Keytype Always des. Master_Key_Length The length of the master key in bytes. Master_Key The master key in hex string format. The policy.prt File The fields in the policy.prt file follow: Rgy_Policy_File_Version An integer representing the version of the policy information. Prop_Read_Version A number indicating the property record's read version. Prop_Write_Version A number indicating the property record's write version. Min_Certificate_Lifetime The minimum amount of time before the principal's ticket must be renewed in weekswdaysdhourshminutesm format. Default_Certificate_Lifetime The the default lifetime for tickets issued to principals in this cell's registry in weekswdaysdhourshminutesm format. Low_Unix_ID_Principal The starting point for principal UNIX IDs automatically generated by the Security Service when a principal is added: an integer, which must be less than Max_Unix_ID. Low_Unix_ID_Group The the starting point for UNIX IDs automatically generated by the Security Service when a group is added: an integer, which must be less than Max_Unix_ID. Low_Unix_ID_Org The starting point for UNIX IDs automatically generated by the Security Service when an organization is added using: an integer, which must be less than Max_Unix_ID. Max_Unix_ID The highest number that can be supplied as a UNIX ID when principals are created: an integer. Rgy_Readonly_Flag An indication of whether or not the registry is read-only: true=read only, false=updateable. Auth_Certificate_Unbound_Flag An indication of whether or not certificates are generated for use on any machine: true=yes, false=no. Shadow_Passwd_Flag Determines whether encrypted passwords are sent over the network: true=encrypted passwords are not sent over the network, false=encrypted passwords are sent over the network. Embedded_Unix_ID_Flag Determines if UNIX IDs are embedded in person, group, and organization UUIDs: true=UNIX IDs are embedded, false=UNIX IDs are not embedded. Realm_Name The name of the full global pathname of realm running the secd. Realm_UUID The UUID of the realm running the secd. Unauthenticated_Quota The quota of unauthenticated users: a number or unlimited. Acct_Lifetime The period during which accounts are valid: a integer number representing days or forever. Passwd_Min_Len The minimum length of passwords: a non-negative integer. Passwd_Lifetime The span in days of the password lifetimes: an integer or forever. Passwd_Expire_Time The date and time the passwords expire in yyyy/mm/dd.hh:mm format. (The first two digits of the year, the hours and the minutes are optional.) Passwd_All_Spaces_Ok An indication of whether or not passwords can consist of all spaces: true=can consist of spaces, false=cannot. Passwd_All_Alphanumeric_Ok Am indication of whether or not passwords can consist of all alphanumeric characters: true=can be all alpha- numeric, false=cannot. Max_Certificate_Lifetime The number of hours before the Authentication Service must renew service certificates: an integer indicating the time in hours or default-policy to use the registry default. Max_Renewable_Lifetime The number of hours before sessions expire and the session principal must log in again to reauthenticate: an integer indicating the time in hours or default- policy to use the registry default. Princ_Cache_State The timestamp of the principal cache. Group_Cache_State The timestamp of the group cache. Org_Cache_State The timestamp of the organization cache. My_Name The cell-relative name of the security server. Master_Key_Version The integer version of current master key. Master_Key_Keytype Always des. Master_Key_Length The length of the master key in bytes. Master_Key The master key in hex string format. Old_Master_Key_Version The version of the previous master key. Old_Master_Key_Keytype Always des. Old_Master_Key_Length: The length of the previous master key in bytes. Old_Master_Key: The previous master key in hex string format. Obj_Acl_Def_Cell_Name: The default cell name of the policy object ACL. Num_Acl_Entries: The number of entries in the policy object ACL. Obj_Acl_Entry*+ The contents of the policy object ACL. The rgy_state.prt File The fields in the rgy_state.prt file follow: Rgy_State_File_Version The integer version number of the format of the rgy_state file. Replica_State The state of the master registry: unknown_to_master, uninitialized, in_service, in_maintenance, closed, deleted, or initializing. Cell_UUID The UUID of cell in which the secd resides. Server_UUID The UUID of this secd. Initialization_UUID The UUID of the last initialization event. Master_File_Version The version number of the master replica. Master_Known_Flag An indicate of whether or not the master replica is known to this replica: true=known, false=not known. Only if this field is true do the other master field contain valid information. Master_UUID The UUID of the master replica. Master_Seqno: The 2-digit sequence number of the event when the master became the master in n.n format. The replicas.prt File The fields in the replicas.prt file follow: Record_Number The sequential number of the record in the database. Replica_UUID The UUID listed for the replica in the replica list. Replica_Name The name of the replica as known to the Cell Directory Service. Num_Towers The number of towers. Tower_Length* The Length of the next tower (in bytes). Tower* The tower used to communicate with the replica (a byte stream that can be broken on word boundaries). Propagation_Type An indication of whether the replica is initialized, initializing, in the process of being updated, or in the process of being deleted. Initialization_UUID UUID of the last initialization. ERROR CONDITIONS You receive the following error message if the default rgy_data directory is being used and there is an advisory lock on the rgy_state data file: Registry: Error - database is locked. Put secd into maintenance mode or clear advisory lock on rgy_state file in db_pathname The existence of the advisory lock implies that secd is in service. Use the sec_admin command to put secd in maintenance mode. If secd is not running, the advisory lock may be the result of an ungraceful shutdown of secd. To remove the advisory lock, use the rename command to rename the DCE$LOCAL:[VAR.SECURITY.RGY_DATA]RGY_STATE.; file, and then change it back to its original name. Then rerun the sec_salvage_db command. 3 Admin_File This section describes v5srvtab, a DCE Security file used for system administration. NAME v5srvtab - The server and machine keytab file DESCRIPTION The DCE$LOCAL:[KRB5]V5SRVTAB.; file is a file on the local node created by the rgy_edit command, the sec_create_db command, or any application that makes sec_key_mgmt() calls. The file contains passwords for servers and machine accounts. To view or manipulate the contents of this file, use the sec_key_mgmt API, described in the OSF DCE Application Development Guide - Core Components and the OSF DCE Application Development Reference. RELATED INFORMATION BOOKS: OSF DCE Application Development Guide - Core Components OSF DCE Application Development Reference 3 API_Intro NAME sec_intro - Application Program Interface to the DCE Security Service DESCRIPTION The Distributed Computing Environment (DCE) Security Service Application Program Interface (API) allows developers to create network services with complete access to all the authentication and authorization capabilities of DCE Security Service and facilities. The transaction of a network service generally consists of a client process requesting some action from a server process. The client may itself be a server, or a user, and the server may also be a client of other servers. Before the targeted server executes the specified action, it must be sure of the client's identity, and it must know whether the client is authorized to request the service. The Security Service API consists of the following sets of Remote Procedure Calls (RPCs) used to communicate with various security- related services and facilities: + rgy - Maintains the network registry of principal identities. + era - Maintains extended registry attributes. + login - Validates a principal's network identity and establish delegated identities. + epa - Extracts privilege attributes from an opaque binding handle. + acl - Implements an Access Control List (ACL) protocol for the authorization of a principal to network access and services. + key - Provides facilities for the maintenance of account keys for daemon principals. + id - Maps file system names to Universal Unique IDs (UUIDs). + pwd_mgmt - Provides facilities for password management. All the calls in this API have names beginning with the sec_ prefix. These are the same calls used by various user-level tools provided as part of the DCE. For example, the sec_create_db tool is written with sec_rgy calls, acl_edit is written with sec_acl calls, and the login program, with which a user logs in to a DCE system, is written using sec_login calls. Most sites will find the user-level tools adequate for their needs, and only must use the Security Service API to customize or replace the functionality of these tools. Though most of the calls in the Security Service API represent RPC transactions, code has been provided on the client side to handle much of the overhead involved with making remote calls. These "stubs" handle binding to the requested security server site, the marshalling of data into whatever form is needed for transmission, and other bookkeeping involved with these remote calls. An application programmer can use the Security Service interfaces as if they were composed of simple C functions. This reference page introduces each of the following APIs: + Registry APIs + Login APIs + Extended Privilege Attributes APIs + Extended Registry Attributes APIs + ACL APIs + Key Management APIs + ID Mapping APIs + Password Management APIs The section for each API is organized as follows: + Synopsis + Data Types + Constants + Files 4 REGISTRY_API_DATA_TYPES SYNOPSIS #include DATA TYPES The following data types are used in sec_rgy_ calls: sec_rgy_handle_t A pointer to the registry server handle. The registry server is bound to a handle with the sec_rgy_site_open() routine. sec_rgy_bind_auth_info_type_t A enumeration that defines whether or not the binding is authenticated. This data type is used in conjunction with the sec_rgy_bind_auth_info_t data type to set up the authorization method and parameters for a binding. The sec_rgy_bind_auth_info_type_t type consists of the following elements: + sec_rgy_bind_auth_none-The binding is not authenticated. + sec_rgy_bind_auth_dce-The binding uses DCE shared-secret key authentication. sec_rgy_bind_auth_info_t A discriminated union that defines authorization and authentication parameters for a binding. This data type is used in conjunction with the sec_rgy_bind_auth_info_type_t data type to set up the authorization method and parameters for a binding. The sec_rgy_bind_auth_info_t data type consists of the following elements: info_type A sec_rgy_bind_auth_info_type_t data type that specifies whether or not the binding is authenticated. The contents of the union depend on the value of sec_rgy_bind_auth_info_type_t. For unauthenticated bindings (sec_rgy_bind_auth_info_type_t = sec_rgy_bind_auth_none), no parameters are supplied. For authenticated bindings (sec_rgy_bind_auth_info_type_t = sec_rgy_bind_auth_dce), the dce_info structure is supplied. dce_info A structure that consists of the following elements: authn_level An unsigned 32 bit integer indicating the protection level for RPC calls made using the server binding handle. The protection level determines the degree to which authenticated communications between the client and the server are protected by the authentication service specified by authn_svc. If the RPC runtime or the RPC protocol in the bound protocol sequence does not support a specified level, the level is automatically upgraded to the next higher supported level. The possible protection levels are as follows: + rpc_c_protect_level_default - Uses the default protection level for the specified authentication service. The default protection level for DCE shared-secret key authentication is rpc_c_protect_level_pkt_value + rpc_c_protect_level_none - Performs no authentication: tickets are not exchanged, session keys are not established, client PACs or names are not certified, and trans- missions are in the clear. Note that although uncertified PACs should not be trusted, they may be useful for debugging, tracing, and measurement purposes. + rpc_c_protect_level_connect - Authenticates only when the client establishes a rela- tionship with the server. + rpc_c_protect_level_call - Authenticates only at the beginning of each remote procedure call when the server receives the request. This level does not apply to remote procedure calls made over a connection-based protocol sequence (that is, ncacn_ip_tcp). If this level is specified and the binding handle uses a connection-based protocol sequence, the routine uses the rpc_c_protect_level_pkt level instead. + rpc_c_protect_level_pkt - Ensures that all data received is from the expected client. + rpc_c_protect_level_pkt_integ - Ensures and verifies that none of the data trans- ferred between client and server has been modified. This is the highest protection level that is guaranteed to be present in the RPC runtime. + rpc_c_protect_level_pkt_privacy - Authenticates as specified by all of the previous levels and also encrypts each RPC argument value. This is the highest protection level, but is not guaranteed to be present in the RPC runtime. authn_svc Specifies the authentication service to use. The exact level of protection provided by the authentication service is specified by protect_level. The supported authentication services are as follows: + rpc_c_authn_none - No authentication: no tickets are exchanged, no session keys established, client PACs or names are not transmitted, and transmissions are in the clear. Specify rpc_c_authn_none to turn authentication off for remote procedure calls made using this binding. + rpc_c_authn_dce_secret - DCE shared-secret key authentication. + rpc_c_authn_default - Default authentica- tion service. The current default authen- tication service is DCE shared-secret key; therefore, specifying rpc_c_authn_default is equivalent to specifying rpc_c_authn_dce_secret . + rpc_c_authn_dce_public - DCE public key authentication (reserved for future use). authz_svc Specifies the authorization service implemented by the server for the interface. The validity and trustworthiness of authorization data, like any application data, is dependent on the authentication service and protection level specified. The supported authorization services are as follows: + rpc_c_authz_none - Server performs no authorization. This is valid only if authn_svc is set to rpc_c_authn_none, specifying that no authentication is being performed. + rpc_c_authz_name - Server performs authorization based on the client principal name. This value cannot be used if authn_svc is rpc_c_authn_none. + rpc_c_authz_dce - Server performs authorization using the client's DCE Privilege Attribute Certificate (PAC) sent to the server with each remote procedure call made with this binding. Generally, access is checked against DCE Access Control Lists (ACLs). identity A value of type sec_login_handle_t that represents a complete login context. sec_timeval_sec_t A 32-bit integer containing the seconds portion of a UNIX timeval_t, to be used when expressing absolute dates. sec_timeval_t A structure containing the full UNIX time. The structure contains two 32-bit integers that indicate seconds (sec) and microseconds (usec) since 0:00, January 1, 1970. sec_timeval_period_t A 32-bit integer expressing seconds relative to some well-known time. sec_rgy_acct_key_t Specifies how many parts (person, group, organization) of an account login name will be enough to specify a unique abbreviation for that account. sec_rgy_cursor_t A structure providing a pointer into a registry database. This type is used for iterative operations on the registry information. For example, a call to sec_rgy_pgo_get_members() might return the 10 account names following the input sec_rgy_cursor_t position. Upon return, the cursor position will have been updated, so the next call to that routine will return the next 10 names. The components of this structure are not used by application programs. sec_rgy_pname_t A character string of length sec_rgy_pname_t_size. sec_rgy_name_t A character string of length sec_rgy_name_t_size. sec_rgy_login_name_t A structure representing an account login name. It contains three strings of type sec_rgy_name_t: pname The person name for the account. gname The group name for the account. oname The organization name for the account. sec_rgy_member_t A character string of length sec_rgy_name_t_size. LI "sec_rgy_foreign_id_t" The representation of a foreign ID. This structure contains two components: cell A string of type uuid_t representing the UUID of the foreign cell. principal A string of type uuid_t representing the UUID of the principal. sec_rgy_sid_t A structure identifying an account. It contains three fields: person The UUID of the person part of the account. group The UUID of the group part of the account. org The UUID of the organization part of the account. sec_rgy_unix_sid_t A structure identifying an account with UNIX ID numbers. It contains three fields: person The UNIX ID of the person part of the account. group The UNIX ID of the group part of the account. org The UNIX ID of the organization part of the account. sec_rgy_domain_t This 32-bit integer specifies which naming domain a character string refers to: person, group, or organization. sec_rgy_pgo_flags_t A 32-bit bitset containing flags pertaining to registry entries. This type contains the following three flags: sec_rgy_pgo_is_an_alias If set, indicates the registry entry is an alias of another entry. sec_rgy_pgo_is_required If set, the registry item is required and cannot be deleted. An example of a required account is the one for the registry server itself. sec_rgy_pgo_projlist_ok If the accompanying item is a person entry, this flag indicates the person may have concurrent group sets. If the item is a group entry, the flag means this group can appear in a concurrent group set. The flag is undefined for organization items. sec_rgy_pgo_item_t The structure identifying a registry item. It contains five com- ponents: id The UUID of the registry item, in uuid_t form. unix_num A 32-bit integer containing the UNIX ID number of the registry item. quota A 32-bit integer representing the maximum number of user- defined groups the account owner can create. flags A sec_rgy_pgo_flags_t bitset containing information about the entry. fullname A sec_rgy_pname_t character string containing a full name for the registry entry. For a person entry, this field might contain the real name of the account owner. For a group, it might contain a description of the group. This is just a data field, and registry queries cannot search on the fullname entry. sec_rgy_acct_admin_flags_t A 32-bit bitset containing administration flags used as part of the administrator's information for any registry account. The set contains three flags: sec_rgy_acct_admin_valid Specifies that the account is valid for login. sec_rgy_acct_admin_server If set, the account's name can be used as a server name in a ticket-granting ticket. sec_rgy_acct_admin_client If set, the account's name can be used as a client name in a ticket-granting ticket. Note that you can prevent the principal from being authenticated, by turning off both the sec_rgy_acct_admin_server and the sec_rgy_acct_admin_client flags. sec_rgy_acct_auth_flags_t A 32-bit bitset containing account authorization flags used to implement authentication policy as defined by the Kerberos Version 5 protocol. The set contains six flags: sec_rgy_acct_auth_post_dated Allows issuance of post-dated certificates. sec_rgy_acct_auth_forwardable Allows issuance of forwardable certificates. sec_rgy_acct_auth_tgt Allows issuance of certificates based on Ticket-Granting Ticket (TGT) authentication. If this flag is not set, a client requesting a service may have to supply a password directly to the server. sec_rgy_acct_auth_renewable Allows issuance of renewable certificates. sec_rgy_acct_auth_proxiable Allows issuance of proxiable certificates. sec_rgy_acct_auth_dup_session_key Allows issuance of duplicate session keys. sec_rgy_acct_admin_t The portion of a registry account item containing components relevant to administrators. This structure consists of the fields listed below. Note that only expiration_date, good_since_date, flags, and authentication_flags can be modified by an administrator; the remaining fields are set by the Security server. creator This field, in foreign_id_t format, identifies the administrator who created the registry account. creation_date Specifies the creation date of the account, in sec_timeval_sec_t format. last_changer Identifies the last person to change any of the account information, in foreign_id_t format. change_date Specifies the date of the last modification of the account information, in sec_timeval_sec_t format. expiration_date The date after which the account will no longer be valid. In sec_timeval_sec_t format. good_since_date The Kerberos Version 5 TGT revocation date. TGTs issued before this date will not be honored. In sec_timeval_sec_t format. flags Administrative flags in sec_rgy_acct_admin_flags_t format. authentication_flags Authentication flags in sec_rgy_acct_auth_flags_t format. sec_rgy_acct_user_flags_t A 32-bit bitset containing flags controlling user-modifiable information. There is only one flag currently implemented. If sec_rgy_acct_user_passwd_valid is set, it indicates the user pass- word is valid. If it is not set, this flag prompts the user to change the password on the next login attempt. sec_rgy_acct_user_t A structure containing registry account information. The structure consists of the fields listed below. Note that only the gecos, homedir, shell, and flags fields can be modified by the account owner or other authorized useer; the remaining fields are set by the Security server. gecos This is a character string (in sec_rgy_pname_t format) containing information about the account user. It generally consists of everything after the full name in the UNIX gecos format. homedir The login directory for the account user, in sec_rgy_pname_t format. shell The default shell for the account user, in sec_rgy_pname_t format. passwd_version_number An unsigned 32-bit integer, indicating the password version number. This value is used as output only. passwd The UNIX encrypted account password, in sec_rgy_unix_passwd_buf_t format. This value is used as output only. passwd_dtm The date the password was established, in sec_timeval_sec_t format. flags Account user flags, in sec_rgy_acct_user_flags_t format. sec_rgy_plcy_pwd_flags_t A 32-bit bitset containing two flags about password policy: sec_rgy_plcy_pwd_no_spaces If set, will not allow spaces in a password. sec_rgy_plcy_pwd_non_alpha If set, requires at least one nonalphanumeric character in the password. sec_rgy_plcy_t A structure defining aspects of registry account policy. It contains five components: passwd_min_len A 32-bit integer describing the minimum number of characters in the account password. passwd_lifetime The number of seconds after a password's creation until it expires, in sec_timeval_period_t format. passwd_exp_date The expiration date of the account password, in sec_timeval_sec_t format. acct_lifespan The number of seconds after the creation of an account before it expires, in sec_timeval_period_t format. passwd_flags Account password policy flags, in sec_rgy_plcy_pwd_flags_t format. sec_rgy_plcy_auth_t This type describes authentication policy. It is a structure containing two time periods, in sec_timeval_period_t format. One, max_ticket_lifetime, specifies the maximum length of the period during which a Ticket-Granting Ticket (TGT) will be valid. The other, max_renewable_lifetime, specifies the maximum length of time for which such a ticket may be renewed. This authentication policy applies both to the registry as a whole as well as individual accounts. The effective policy for a given account is defined to bethe more restrictive of the site and principal authen- tication policy. sec_rgy_properties_t A structure describing some registry properties. It contains the following: read_version A 32-bit integer describing the earliest version of the secd software that can read this registry. write_version A 32-bit integer describing the version of the secd soft- ware that wrote this registry. minimum_ticket_lifetime The minimum lifetime of an authentication certificate, in sec_timeval_period_t format. default_certificate_lifetime The "normal" lifetime of an an authentication certificate (ticket-granting ticket in Kerberos parlance), in sec_timeval_period_t format. Processes may request authentication certificates with longer lifetimes up to, but not in excess of, the maximum allowable lifetime as determined by the effective policy for the account. low_unix_id_person The lowest UNIX number permissible for a person item in the registry. low_unix_id_group The lowest UNIX number permissible for a group item in the registry. low_unix_id_org The lowest UNIX number permissible for an organization item in the registry. max_unix_id The largest UNIX number permissible for any registry entry. flags Property flags, in sec_rgy_properties_flags_t format. realm The name of the cell, in sec_rgy_name_t form, for which this registry is the authentication service. realm_uuid The UUID of the same cell. sec_rgy_properties_flags_t A 32-bit bitset, containing flags concerning registry properties: sec_rgy_prop_readonly If set (TRUE), indicates that this registry is a query site. sec_rgy_prop_auth_cert_unbound If set (TRUE), the registry server will accept requests from any site. sec_rgy_prop_shadow_passwd If the shadow password flag is set (TRUE), the registry server will not include the account password when responding to a request for the user data from a specified account. This helps minimize the risk of an account password being intercepted while traveling over the network. sec_rgy_prop_embedded_unix_id Indicates that all UUIDs in this registry contain a UNIX number embedded. This implies that the UNIX numbers of objects in the registry cannot be changed, since UUIDs are immutable. sec_rgy_override_t A 32-bit integer used as a flag for registry override mode. Currently, its possible values are the constants sec_rgy_no_override and sec_rgy_override. When this mode is enabled, override data supplied by the node administrator will replace some of the data gotten from the registry for a given person/account under certain conditions. These conditions are as follows: 1. The registry permits the requested overrides to be set for this machine. 2. The override data is intended for person/account at hand. When the mode is "override off," data from the registry is returned to the end user or the application remains untouched. sec_rgy_mode_resolve_t A 32-bit integer used as a flag for resolve mode. Currently, its possible values are the constants sec_rgy_no_resolve_pname and sec_rgy_resolve_pname. When the mode is enabled, pathnames containing leading // (slashes) will be translated into a form understandable by the local machine's NFS. sec_rgy_unix_passwd_buf_t A character array of UNIX password strings. CONSTANTS The following constants are used in sec_rgy_ calls: sec_rgy_default_handle The value of an unbound registry server handle. sec_rgy_acct_key_t Constants The following 32-bit integer constants are used with the sec_rgy_acct_key_t data type: sec_rgy_acct_key_none Invalid key. sec_rgy_acct_key_person The person name alone is enough. sec_rgy_acct_key_group The person and group names are both necessary for the account abbreviation. sec_rgy_acct_key_org The person, group, and organization names are all necessary. sec_rgy_acct_key_last Key values must be less than this constant. sec_rgy_pname_t_size The maximum number of characters in a sec_rgy_pname_t. sec_rgy_name_t_size The maximum number of characters in a sec_rgy_name_t. sec_rgy_domain_t Constants The following 32-bit integer constants are the possible values of the sec_rgy_domain_t data type: sec_rgy_domain_person The name in question refers to a person. sec_rgy_domain_group The name in question refers to a group. sec_rgy_domain_org The name in question refers to an organization. sec_rgy_pgo_flags_t A 32-bit constant equal to a variable of type sec_rgy_pgo_flags_t with no flags set. sec_rgy_quota_unlimited A 32-bit integer. Set the quota field of the sec_rgy_pgo_item_t type to this constant to override the registry quota limitation. sec_rgy_acct_admin_flags_t A 32-bit integer. This is the value of the sec_rgy_acct_admin_flags_t bitset when none of its flags are set. sec_rgy_acct_auth_flags_none A 32-bit integer. This is the value of the sec_rgy_acct_auth_flags_t bitset when none of its flags are set. sec_rgy_acct_user_flags_t A 16-bit integer. This is the value of the sec_rgy_acct_user_flags_t bitset when none of its flags are set. sec_rgy_plcy_pwd_flags_t A 16-bit integer. This is the value of the sec_rgy_policy_pwd_flags_t bitset when none of its flags are set. sec_rgy_properties_flags_t A 16-bit integer. This is the value of the sec_rgy_properties_flags_t bitset when none of its flags are set. sec_rgy_override A 32-bit integer, which turns registry override mode on. When this mode is enabled, override data supplied by the node administrator will replace some of the data gotten from the registry for a given person/account under certain conditions. sec_rgy_no_override A 32-bit integer, which turns off registry override mode. sec_rgy_resolve_pname A 32-bit integer, which turns on registry resolve mode. When the mode is enabled, pathnames containing leading // (slashes) will be translated into a form understandable by the local machine's NFS. sec_rgy_no_resolve_pname A 32-bit integer, which turns off registry resolve mode. FILES SYS$COMMON:[DCE$LIBRARY]RGYBASE.IDL The idl file from which rgybase.h was derived. 4 EXTENDED_REGISTRY_ATTRIBUTE_DATA_TYPES SYNOPSIS #include DATA TYPES The following data types are used in sec_rgy_attr calls: sec_attr_twr_ref_t A pointer to a tower. This data type is used with the sec_attr_twr_set_t data type to allow a client to pass an unallocated array of towers, which the server must allocate. Both data types are used in conjunction with the sec_attr_bind_type_t data type. sec_attr_twr_set_t A structure that defines an array of towers. This data type is used with the sec_attr_twr_ref_t data type to allow a client to pass an unallocated array of towers, which the server must allocate. Both data types are used in conjunction with the sec_attr_bind_type_t data type. The sec_attr_twr_set_t structure consists of the following elements: count An unsigned 32-bit integer specifying the number of towers in the array. towers[] An array of pointers (of type sec_attr_twr_ref_t) to towers. sec_attr_bind_type_t A 32-bit integer that specifies the type of binding used by an attribute interface. The data type (which is used in conjunction with the sec_attr_binding_t data type) uses the following constants: sec_attr_bind_type_string An RPC string binding. sec_attr_bind_type_twrs A DCE protocol tower representation of a bindings. sec_attr_bind_type_svrname A name in rpc_c_ns_syntax format that identifies a CDS entry containing the server's binding information. This constant has the following structure: name_syntax Must be rpc_c_ns_syntax_dce to specify that DCE naming rules are used to specify name. name A pointer to a name of a CDS entry in rpc_c_ns_syntax_dce syntax. sec_attr_binding_t A discriminated union that supplies information to generate a binding handle for a attribute trigger. This data type, which is used in conjunction with the sec_attr_bind_info_t data type, is composed of the following elements: bind_type A value of type sec_attr_bind_type_t that defines the type of binding used by an attribute interface. The contents of tagged union (below) depend on the value of sec_attr_bind_type_t. tagged_union A tagged union specifying the binding handle. The contents of the tagged union depend on the value of bind_type as follows: If bind_type is... Then tagged_union is... _______________________________________________________________________ sec_attr_bind_type_string A pointer to an unsigned 32-bit character string specifying an attribute's RPC string binding. _______________________________________________________________________ sec_attr_bind type_twrs An attribute's tower binding representation of type sec_attr_twr_set_t. _______________________________________________________________________ sec_attr_bind_svrname A pointer to a name of type sec_attr_bind_type_t that specifies a Cell Directory Service entry containing an attribute trigger's binding information. sec_attr_binding_p_t A pointer to a sec_attr_binding_t union. sec_attr_bind_auth_info_type_t An enumeration that defines whether or not the binding is authenti- cated. This data type is used in conjunction with the sec_attr_bind_auth_info_t data type to set up the authorization method and parameters for an RPC binding. The sec_attr_bind_auth_info_type_t type consists of the following elements: + sec_attr_bind_auth_none-The binding is not authenticated. + sec_attr_bind_auth_dce-The binding uses DCE shared-secret key authentication. sec_attr_bind_auth_info_t A discriminated union that defines authorization and authentication parameters for a binding. This data type is used in conjunction with the sec_attr_bind_auth_info_type_t data type to set up the authorization method and parameters for an RPC binding. The sec_attr_bind_auth_info_t data type consists of the following elements: info_type A sec_attr_bind_auth_info_type_t data type that specifies whether or not the binding is authenticated. The contents of tagged union (below) depend on the value of sec_attr_bind_auth_info_type_t. tagged_union A tagged union specifying the method of authorization and the authorization parameters. For unauthenticated bindings (sec_attr_bind_auth_info_type_t = sec_attr_bind_auth_none) no parameters are supplied. For authenticated bindings (sec_attr_bind_auth_info_type_t = sec_attr_bind_auth_dce), the following union is supplied: svr_princ_name A pointer to a character string that specifies the principal name of the server referenced by the binding handle. protect_level An unsigned 32 bit integer indicating the protection level for RPC calls made using the server binding handle. The protection level determines the degree to which authenticated communications between the client and the server are protected by the authentication service specified by authn_svc. If the RPC runtime or the RPC protocol in the bound protocol sequence does not support a specified level, the level is automatically upgraded to the next higher supported level. The possible protection levels are as follows: + rpc_c_protect_level_default - Uses the default protection level for the specified authentication service. The default protection level for DCE shared-secret key authentication is rpc_c_protect_level_pkt_value + rpc_c_protect_level_none - Performs no authentication: tickets are not exchanged, session keys are not established, client PACs or names are not certified, and transmissions are in the clear. Note that although uncertified PACs should not be trusted, they may be useful for debugging, tracing, and measurement purposes. + rpc_c_protect_level_connect - Authenticates only when the client establishes a relationship with the server. + rpc_c_protect_level_call - Authenticates only at the beginning of each remote procedure call when the server receives the request. This level does not apply to remote procedure calls made over a connection-based protocol sequence (that is, ncacn_ip_tcp). If this level is specified and the binding handle uses a connection-based protocol sequence, the routine uses the rpc_c_protect_level_pkt level instead. + rpc_c_protect_level_pkt - Ensures that all data received is from the expected client. + rpc_c_protect_level_pkt_integ - Ensures and verifies that none of the data trans- ferred between client and server has been modified. This is the highest protection level that is guaranteed to be present in the RPC runtime. + rpc_c_protect_level_pkt_privacy - Authenticates as specified by all of the previous levels and also encrypts each RPC argument value. This is the highest protection level, but is not guaranteed to be present in the RPC runtime. authn_svc Specifies the authentication service to use. The exact level of protection provided by the authentication service is specified by protect_level. The supported authentication services are as follows: + rpc_c_authn_none - No authentication: no tickets are exchanged, no session keys established, client PACs or names are not transmitted, and transmissions are in the clear. Specify rpc_c_authn_none to turn authentication off for remote procedure calls made using this binding. + rpc_c_authn_dce_secret - DCE shared-secret key authentication. + rpc_c_authn_default - Default authentica- tion service. The current default authen- tication service is DCE shared-secret key; therefore, specifying rpc_c_authn_default is equivalent to specifying rpc_c_authn_dce_secret. + rpc_c_authn_dce_public - DCE public key authentication (reserved for future use). authz_svc Specifies the authorization service implemented by the server for the interface. The validity and trustworthiness of authorization data, like any application data, is dependent on the authentication service and protection level specified. The supported authorization services are as follows: + rpc_c_authz_none - Server performs no authorization. This is valid only if authn_svc is set to rpc_c_authn_none, specifying that no authentication is being performed. + rpc_c_authz_name - Server performs authorization based on the client principal name. This value cannot be used if authn_svc is rpc_c_authn_none. + rpc_c_authz_dce - Server performs authorization using the client's DCE Privilege Attribute Certificate (PAC) sent to the server with each remote procedure call made with this binding. Generally, access is checked against DCE Access Control Lists (ACLs). sec_attr_bind_info_t A structure that specifies attribute trigger binding information. This data type, which is used in conjunction with the sec_attr_schema_entry_t data type, contains of the following elements: auth_info The binding authorization information of type sec_attr_bind_auth_info_t. num_bindings An unsigned 32-bit integer specifying the number of binding handles in bindings. bindings An array of sec_attr_binding_t data types that specify binding handles. sec_attr_bind_info_p_t A pointer to a sec_attr_bind_info_t union. sec_attr_encoding_t An enumerator that contains attribute encoding tags used to define the legal encodings for attribute values. The data type, which is used in conjunction with the sec_attr_value_t and sec_attr_schema_entry_t data types, consists of the following elements: sec_attr_enc_any The attribute value can be of any legal encoding type. This encoding tag is legal only in a schema entry. An attribute entry must contain a concrete encoding type. sec_attr_enc_void The attribute has no value. It is simple a marker that is either present or absent. sec_attr_enc_printstring The attribute value is a printable IDL string in DCE Portable Character Set. sec_attr_enc_printstring_array The attribute value is an array of printstrings. sec_attr_enc_integer The attribute value is a signed 32-bit integer. sec_attr_enc_bytes The attribute value is a string of bytes. The string is assumed to be a pickle or some other self describing type. (See also the sec_attr_enc_bytes_t data type.) sec_attr_enc_confidential_bytes The attribute value is a string of bytes that have been encrypted in the key of the principal object to which the attribute is attached. The string is assumed to be a pickle or some other self describing type. This encoding type is useful only when attached to a principal object, where it is decrypted and encrypted each time the principal's password changes. (See also the sec_attr_enc_bytes_t data type.) sec_attr_enc_i18n_data The attribute value is an "internationalized" string of bytes with a tag identifying the OSF registered codeset used to encode the data. (See also the sec_attr_i18n_data_t data type.) sec_attr_enc_uuid The attribute is a value of type uuid_t, a DCE UUID. sec_attr_enc_attr_set The attribute value is an attribute set, a vector of attribute UUIDs used to associate multiple related attribute instances which are members of the set. (See also the sec_attr_enc_attr_set_t data type.) sec_attr_enc_binding The attribute value is a sec_attr_bind_info_t data type that specifies DCE server binding information. sec_attr_enc_trig_binding This encoding type is returned by rs_attr_lookup call. It informs the client agent of the trigger binding informa- tion of an attribute with a query trigger. Unless sec_attr_enc_void or sec_attr_enc_any is specified, the attribute values must conform to the attribute's encoding type. sec_attr_enc_bytes_t A structure that defines the length of attribute encoding values for attributes encoded as sec_attr_enc_bytes and sec_attr_enc_confidential_bytes. The structure, which is used in conjunction with the sec_attr_value_t data type, consists of: An unsigned 32-bit integer that defines the data length. data[] An array of bytes specifying the length of attribute encoding data. sec_attr_i18n_data_t A structure that defines the codeset used for attributes encoded as sec_attr_enc_il8n_data and the length of the attribute encoding values. The structure, which is used in conjunction with the sec_attr_value_t data type, consists of: An unsigned 32-bit identifier of a codeset registered with the Open Software Foundation. An unsigned 32-bit integer that defines the data length. data[] An array of bytes specifying the length of attribute encoding data. sec_attr_enc_attr_set_t A structure that that supplies the UUIDs of each member of an attribute set. The structure, which is used in conjunction with the sec_attr_value_t data type, consists of: num_members An unsigned 32-bit integer specifying the total number of attribute's in the set. members[] An array containing values of type uuid_t, the UUID of each member in the set. sec_attr_enc_printstring_t A structure that contains a printstring. sec_attr_enc_printstring_p_t A pointer to a sec_attr_enc_printstring_t structure. sec_attr_enc_str_array_t A structure that defines a printstring array. It consists of: num_strings An unsigned 32-bit integer specifying the number of strings in the array. strings[] An array of pointers (of type sec_attr_enc_print_string_p_t) to printstrings. sec_attr_value_t A discriminated union that defines attribute values. The union, which is used in conjunction with the sec_attr_t data type, consists of the following elements: attr_encoding A sec_attr_encoding_t data type that defines attribute encoding. The contents of tagged union (below) depend on the value of sec_attr_encoding_t. tagged_union A tagged union whose contents depend on attr_encoding as follows: If attr_encoding is... Then tagged_union is... _______________________________________________________________________ sec_attr_enc_void NULL _______________________________________________________________________ sec_attr_enc_printstring A pointer to printstring _______________________________________________________________________ sec_attr_enc_printstring_array A pointer to an array of printstrings _______________________________________________________________________ sec_attr_enc_integer signed_int, a 32-bit signed integer _______________________________________________________________________ sec_attr_enc_bytes bytes, a pointer to a structure of type sec_attr_enc_bytes_t _______________________________________________________________________ sec_attr_enc_confidential_bytes bytes, a pointer to a structure of type sec_attr_enc_bytes_t _______________________________________________________________________ sec_attr_enc_i18n_data idata, a pointer to a structure of type sec_attr_i18n_data_t _______________________________________________________________________ sec_attr_end_uuid uuid, a value of type uuid_t _______________________________________________________________________ sec_attr_enc_attr_set attr_set, a pointer to a structure of type sec_attr_enc_attr_set_t _______________________________________________________________________ sec_attr_enc_binding binding, a pointer to a structure of type sec_attr_binding_info_t sec_attr_t A structure that defines an attribute. The structure consists of: attr_id A value of type uuid_t, the UUID of the attribute. attr_value A value of type sec_attr_value_t. sec_attr_acl_mgr_info_t A structure that contains the access control information defined in a schema entry for an attribute. The structure, which is used in conjunction with the sec_attr_schema_entry_t data type, consists of the following elements: acl_mgr_type The value of type uuid_t that specifies the UUID of the ACL manager type that supports the object type to which the attribute can be attached. This field provides a well-defined context for evaluating the permission bits needed to operate on the attribute. The following table lists the ACL Manager types for registry objects. Registry Object ACL Manager Type Valid Type Permissions ____________________________________________________________________ principal 06ab9320-0191-11ca-a9e8-08001e039d7d rcDnfmaug ____________________________________________________________________ group 06ab9640-0191-11ca-a9e8-08001e039d7d rctDnfmM ____________________________________________________________________ organization 06ab9960-0191-11ca-a9e8-08001e039d7d rctDnfmM ____________________________________________________________________ directory 06ab9c80-0191-11ca-a9e8-08001e039d7d rcidDn ____________________________________________________________________ policy 06ab8f10-0191-11ca-a9e8-08001e039d7d rcma ____________________________________________________________________ replist 2ac24970-60c3-11cb-b261-08001e039d7d cidmAI query_permset Data of type sec_acl_permset_t that defines the permission bits needed to access the attribute's value. update_permset Data of type sec_acl_permset_t that defines the permission bits needed to update the attribute's value. test_permset Data of type sec_acl_permset_t that defines the permission bits needed to test the attribute's value. delete_permset Data of type sec_acl_permset_t that defines the permission bits needed to delete an attribute instance. sec_attr_acl_mgr_info_p_t A pointer to a sec_attr_acl_mgr_info_t structure. sec_attr_acl_mgr_info_set_t A structure that defines an attribute's ACL manager set. The structure consists of the following elements: num_acl_mgrs An unsigned 32-bit integer that specifies the number of ACL managers in the ACL manager set. mgr_info[] An array of pointers of type sec_attr_mgr_info_p_t that define the ACL manager types in the ACL manager set and the permission sets associated with the ACL manager type. sec_attr_intercell_action_t An enumerator that specifies the action that should be taken by the Privilege Service when it reads acceptable attributes from a foreign cell. A foreign attribute is acceptable only if there is either a schema entry for the foreign cell or if sec_attr_intercell_act_accept is set to true. This enumerator, which is used in conjunction with the sec_attr_schema_entry_t data type, is composed of the following ele- ments: sec_attr_intercell_act_accept If the unique flag in the sec_attr_schema_entry_t data type is not set on, retain the attribute. If the unique flag is set on, retain the attribute only if its value is unique among all attribute instances of the same attribute type within the cell. sec_attr_intercell_act_reject Discard the input attribute. sec_attr_intercell_act_evaluate Use the binding information in the trig_binding field of this sec_attr_schema_entry_t data type to make a sec_attr_trig_query call to a trigger server. That server determines whether to retain the attribute value, discard the attribute value, or map the attribute to another value(s). sec_attr_trig_type_t Specifies the trigger type, a flag that determines whether an attribute trigger should be invoked for query operations. The data type, which is used in conjunction with the sec_attr_schema_entry_t data type, uses the following constants: The attribute trigger server is invoked for query opera- tions. sec_attr_trig_type_query The attribute trigger server is invoked for update opera- tions. sec_attr_schema_entry_t A structure that defines a complete attribute entry for the schema catalog. The entry is identified by both a unique string name and a unique attribute UUID. Although either can either can be used as a retrieval key, the string name should be used for interactive access to the attribute and the UUID for programmatic access. The attribute UUID is used to identify the semantics defined for the attribute type in the schema. The sec_attr_schema_entry_t data type consists of the following ele- ments: attr_name A pointer to the attribute name. attr_id A value of type uuid_t that identifies the attribute type. attr_encoding An enumerator of type sec_attr_encoding_t that specifies the attribute's encoding. acl_mgr_set A structure of type sec_attr_acl_mgr_info_set_t that specifies the ACL manager types that support the objects on which attributes of this type can be created and the permission bits supported by that ACL manager type. schema_entry_flags An unsigned integer of type sec_attr_sch_entry_flags_t that defines bitsets for the following flags: unique When set on, this flag indicates that each instance of this attribute type must have a unique value within the cell for the object type implied by the ACL Manager type. If this flag is not set on, uniqueness checks are not performed for attribute writes. multi_valued When set on, this flag indicates that this attribute type may be multi-valued; in other words, multiple instances of the same attribute type can be attached to a single registry object. If this flag is not set on, only one instance of this attribute type can be attached to an object. reserved When set on, this flag prevents the schema entry from being deleted through any interface or by any user. If this flag is not set on, the entry can be deleted by any authorized principal. use_defaults When set on, the system-defined default attribute value will be returned on a client query if an instance of this attribute does not exist on the queried object. If this flag is not set on, system defaults are not used. intercell_action An enumerator of type sec_attr_intercell_action_t that specifies how the Privilege Service will handle attributes from a foreign cell. trig_types A flag of type sec_attr_trig_type_t that specifies whether whether a trigger can perform update or query operations. trig_binding A pointer to a structure of type sec_attr_bind_info_t that supplies the attribute trigger binding handle. scope A pointer to a string that defines the objects to which the attribute can be attached. comment A pointer to a string that contains general comments about the attribute. sec_attr_schema_entry_parts_t A 32-bit bitset containing flags that specify the schema entry fields that can be modified on a schema entry update operation. This data type contains the following flags: sec_attr_schema_part_name If set, indicates that the attribute name (attr_name) can be changed. sec_attr_schema_part_reserved If set, indicates that the setting of the flag that deter- mines whether or not the schema entry can be deleted (reserved) can be changed. sec_attr_schema_part_defaults If set, indicates that the flag that determines whether or not a query for a non-existent attribute will not result in a search for a system default (apply_default) can be changed. sec_attr_schema_part_trig_bind If set, indicates that the trigger's binding information (trig_binding) can be changed. sec_attr_schema_part_comment If set, indicates whether or not comments associated with the schema entry (comment) can be changed. sec_attr_component_name_t A pointer to a character string used to further specify the object to which the attribute is attached. (Note that this data type is analogous to the sec_acl_component_name_t data type in the ACL interface.) sec_attr_cursor_t A structure that provides a pointer into a registry database and is used for multiple database operations. This cursor must minimally represent the object indicated by xattrschema in the schema interfaces, or component_name in the attribute interfaces. The cursor may additionally represent an entry within that schema or an attribute instance on that component. sec_attr_srch_cursor_t A structure that provides a pointer into a registry database and is used for multiple database operations. The cursor must minimally represent the list of all objects managed by this server that possess the search attributes specified in the sec_attr_srch_cursor_init routine. It may additionally represent a given object within this list as well as attribute instance(s) possessed by that object. sec_attr_trig_cursor_t A structure that provides an attribute trigger cursor for inter- active operations. The structure consists of the following elements: source A value of type uuid_t that provides a UUID to identify the server that initialized the cursor. object_handle A signed 32 bit integer that identifies the object (specified by xattrschema in the schema interface or component_name in the attribute interface) upon which the operation is being performed. entry_handle A signed 32 bit integer that identifies the current entry (schema_entry in the schema interface or attribute instance in the attribute interface) for the operation. valid A boolean field with the following values: + true (1) - Indicates an initialized cursor. + false (0) - Indicates an uninitialized cursor. sec_attr_trig_timeval_sec_t A 32-bit integer containing the seconds portion of a UNIX timeval_t, to be used when expressing absolute dates. FILES SYS$COMMON:[DCE$LIBRARY]SEC_ATTR_BASE.IDL The idl file from which sec_attr_base.h was derived. CONSTANTS The following constants are used in sec_attr calls: sec_attr_bind_auth_dce The binding uses DCE shared-secret key authentication. sec_attr_bind_auth_none The binding is not authenticated. sec_attr_bind_type_string The attribute uses an rpc string binding. sec_attr_bind_type_svrname The attribute uses a name in rpc_c_ns_syntax format that identifies a CDS entry containing the server's binding information. This constant has the following structure: name_syntax Must be rpc_c_ns_syntax_dce to specify that DCE naming rules are used to specify name. name A pointer to a name of a CDS entry in rpc_c_ns_syntax_dce syntax. sec_attr_bind_type_twr The attribute uses a DCE protocol tower binding representation. sec_attr_trig_type_t Constants The following 32-bit constants are used with the sec_attr_trig_type_t data type: sec_attr_trig_type_query The trigger server can perform only query operations. sec_attr_trig_type_update The trigger server can perform only update operations. sec_attr_intercell_action_t Constants The following constants are used with the sec_attr_intercell_action_t data type sec_attr_intercell_act_accept If the unique flag in the sec_attr_schema_entry_t data type is not set on, retain attributes from a foreign cell. If the unique flag is set on, retain the foreign attribute only if its value is unique among all attribute instances of the same attribute type within the cell. sec_attr_intercell_act_reject Discard attributes from a foreign cell. sec_attr_intercell_act_evaluate A trigger server determines whether to retain foreign attributes, discard foreign attributes, or map foreign attribute to another value(s). sec_attr_schema_entry_parts_t Constants The following constants are used with the sec_attr_schema_entry_parts_t data type: sec_attr_schema_part_name Indicates that the attribute name can be changed in an schema update operation. sec_attr_schema_part_reserved Indicates that the setting of the reserved flag can be changed in a schema entry update. sec_attr_schema_part_defaults Indicates that the apply_default flag can be changed in a schema entry update operation. sec_attr_schema_part_trig_bind Indicates that trigger binding information can be changed in a schema entry update operation. sec_attr_schema_part_comment Indicates that comments associated with the schema entry can be changed in a schema entry update. 4 LOGIN_API_DATA_TYPES SYNOPSIS #include DATA TYPES The following data types are used in sec_login_ calls: sec_login_handle_t This is an opaque pointer to a data structure representing a complete login context. The context includes a principal's network credentials, as well as other account information. The network credentials are also referred to as the principal's "ticket-granting ticket." sec_login_flags_t A 32-bit set of flags describing restrictions on the use of a principal's validated network credentials. Currently, only one flag is implemented, and the set can take on the following two values: sec_login_no_flags No special flags are set. sec_login_credentials_private Restricts the validated network credentials to the current process. If this flag is not set, it is permissible to share credentials with descendents of current process. sec_login_auth_src_t An enumerated set describing how the login context was authorized. The possible values are: sec_login_auth_src_network Authentication accomplished through the normal network authority. A login context authenticated this way will have all the network credentials it ought to have. sec_login_auth_src_local Authentication accomplished via local data. Authentication occurs locally if a principal's account is tailored for the local machine, or if the network authority is unavailable. Since login contexts authenticated locally have no network credentials, they may not be used for network operations. sec_login_auth_src_overridden Authentication accomplished via the override facility. sec_login_passwd_t The sec_login_get_pwent() call will return a pointer to a "password" structure, which depends on the underlying registry structure. In most cases, the structure will look like that supported by Berkeley 4.4BSD and OSF/1, which looks like this: struct passwd { char *pw_name; * user name * char *pw_passwd; * encrypted password * int pw_uid; * user uid * int pw_gid; * user gid * time_t pw_change; * password change time * char *pw_class; * user access class * char *pw_gecos; * Honeywell login info * char *pw_dir; * home directory * char *pw_shell; * default shell * time_t pw_expire; * account expiration * }; sec_passwd_rec_t A structure containing either a plaintext password or a preencrypted buffer of password data. The sec_passwd_rec_t structure consists of three components: version_number The version number of the password. pepper A character string combined with the password before an encryption key is derived from the password. key A structure consists of the following components: key_type The key type can be the following: sec_passwd_plain Indicates that a printable string of data is stored in plain. sec_passwd_des Indicates that an array of data is stored in des_key. tagged_union A structure specifying the password. The value of the structure depends on key_type. If key_type is sec_passwd_plain, structure contains plain, a character string. If key_type is sec_passwd_des, the structure contains des_key, a DES key of type sec_passwd_des_key_t. CONSTANTS The following constants are used in sec_login_ calls: sec_login_default_handle The value of a login context handle before setup or validation. sec_login_flags_t Constants The following two constants are used with the sec_login_flags_t type. sec_login_no_flags No special flags are set. sec_login_credentials_private Restricts the validated network credentials to the current process. If this flag is not set, it is permissible to share credentials with descendents of current process. sec_login_remote_uid Used in the sec_login_passwd_t structure for users from remote cells. sec_login_remote_gid Used in the sec_login_passwd_t structure for users from remote cells. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which sec_login.h was derived. 4 EXTENDED_PRIVILEGE_ATTRIBUTE_API_DATA_TYPES SYNOPSIS #include #include DATA TYPES The following data types are used in Extended Privilege Attribute calls and in the sec_login_cred calls that implement extended privilege attributes. sec_cred_cursor_t A structure that provides an input/output cursor used to iterate through a set of delegates in the sec_cred_get_delegate() or sec_login_cred_get_delegate() calls. This cursor is initialized by the sec_cred_initialize_cursor() or sec_login_cred_init_cursor() call. sec_cred_attr_cursor_t A structure that provides an input/output cursor used to iterate through a set of extended attributes in the sec_cred_get_extended_attributes() call. This cursor is initialized by the sec_cred_initialize_attr_cursor() call. sec_id_opt_req_t A structure that specifies application-defined optional restrictions. The sec_id_opt_req_t data type is composed of the following elements: restriction_len An unsigned 16-bit integer that defines the size of the restriction data. restrictions A pointer to a byte_t that contains the restriction data. sec_rstr_entry_type_t An enumerator that specifies the entry types for delegate and target restrictions. This data type is used in conjunction with the sec_id_restriction_t data type where the specific UUID(s), if appropriate, are supplied. It consists of the following components: sec_rstr_e_type_user The target is a local principal identified by UUID. This type conforms with the POSIX 1003.6 standard. sec_rstr_e_type_group The target is a local group identified by UUID. This type conforms with the POSIX 1003.6 standard. sec_rstr_e_type_foreign_user The target is a foreign principal identified by principal and cell UUID. sec_rstr_e_type_foreign_group The target is a foreign group identified by group and cell UUID. sec_rstr_e_type_foreign_other The target is any principal that can authenticate to the foreign cell identified by UUID. sec_rstr_e_type_any_other The target is any principal that can authenticate to any cell, but is not identified in any other type entry. sec_rstr_e_type_no_other No pincipal can act as a target or delegate. sec_id_restriction_t A discriminated union that defines delegate and target restrictions. The union, which is used in conjunction with the sec_restriction_set_t data type, consists of the following elements: entry_type A sec_rstr_entry_type_t that defines the ACL entry types for delegate and target restrictions. The value of tagged_union depends on the value of entry_type. tagged_union A tagged union whose contents depend on entry_type as fol- lows: If entry_type is... Then tagged_union is... ________________________________________________________________ sec_rstr_e_type_any_other NULL ________________________________________________________________ sec_rstr_e_type_foreign_other foreign_id that identifies the foreign cell. ________________________________________________________________ sec_rstr_e_type_user id, a sec_id_t that sec_rstr_e_type_group identifies the user or group. ________________________________________________________________ sec_rstr_e_type_foreign_user foreign_id, a sec_id_foreign_t sec_rstr_e_type_foreign_group that identifies the foreign user or group. sec_id_restriction_set_t A structure that that supplies delegate and target restrictions. The structure consists of: num_restrictions A 16-bit unsigned integer that defines the number of restrictions in restrictions. restrictions A pointer to a sec_id_restriction_t that contains the res- trictions. sec_id_compatibility_mode_t A unsigned 16 bit integer that defines the compatibility between current and pre-1.1 servers. The data type uses the following con- stants: sec_id_compat_mode_none Compatibility mode is off. sec_id_compat_mode_initiator Compatibility mode is on. The 1.0 PAC data extracted from the EPAC of the chain initiator. sec_id_compat_mode_caller Compatibility mode is on. The 1.0 PAC data extracted from the last delegate in the delegation chain. sec_id_delegation_type_t An unsigned 16 bit integer that defines the delegation type. The data type uses the following constants: sec_id_deleg_type_none Delegation is not allowed. sec_id_deleg_type_traced Traced delegation is allowed. sec_id_deleg_type_impersonation Simple (impersonation) delegation is allowed. sec_id_pa_t An structure that contains pre-1.1 PAC data extracted from an EPAC of a current version server. This data type, which is used for compatibility with pre-1.1 servers, consists of the following elements: realm A value of type sec_id_t that contains the UUID that identifies the cell in which the principal associated with the PAC exists. principal A value of type sec_id_t that contains the UUID of the principal. group A value of type sec_id_t that contains the UUID of the principal's primary group. num_groups An unsigned 16-bit integer that specifies the number of groups in the principal's groupset. groups An array of pointers to sec_id_ts that contain the UUIDs of the each group in the principal's groupset. num_foreign_groupsets An unsigned 16-bit integer that specifies the number of foreign groups for the principal's groupset. foreign_groupsets An array of pointers to sec_id_ts that contain the UUIDs of the each group in the principal's groupset. sec_id_pac_t An structure that contains a pre-1.1 PAC. This data type, which is used as output of the sec_cred_get_v1_pac call, consists of the following elements: pac_type A value of type sec_id_pac_format_t that can be used to describe the PAC format. authenticated A boolean field that indicates whether or not the PAC is authenticated (obtained from an authenticated source). FALSE indicates that the PAC is not authenticated. No authentication protocol was used in the rpc that trans- mitted the identity of the caller. TRUE indicates that the PAC is authenticated. realm A value of type sec_id_t that contains the UUID that identifies the cell in which the principal associated with the PAC exists. principal A value of type sec_id_t that contains the UUID of the principal. group For local principals, a value of type sec_id_t that contains the UUID of the principal's primary group. num_groups An unsigned 16-bit integer that specifies the number of groups in the principal's groupset. groups An array of pointers to sec_id_ts that contain the UUIDs of the each group in the principal's groupset. num_foreign_groups An unsigned 16-bit integer that specifies the number of foreign groups in the principal's groupset. foreign_groups An array of pointers to sec_id_ts that contain the UUIDs of the each foreign group in the principal's groupset. sec_id_pac_format_t An enumerator that can be used to describe the PAC format. sec_id_t A structure that contains UUIDs for principals, groups, or organiza- tions and an optional printstring name. Since a UUID is an handle for the object's identity, the sec_id_t data type is the basic unit for identifying principals, groups, and organizations. Because the printstring name is dynamically allocated, this datatype requires a destructor function. Generally, however, the sec_id_t is embedded in other data types (ACLs, for example), and these data- types have a destructor function to release the printstring storage. The sec_id_t data type is composed of the following elements: uuid A value of type uuid_t, the UUID of the principal, group, or organization. name A pointer to a character string containing the name of the principal, group, or organization. sec_id_foreign_t A structure that contains UUIDs for principals, groups, or organiza- tions for objects in a foreign cell and the UUID that identifies the foreign cell. The sec_id_foreign_t data type is composed of the following elements: id A value of type sec_id_t that contains the UUIDs of the objects from the foreign cell. realm A value of type sec_id_t that contains the UUID of the foreign cell. sec_id_foreign_groupset_t A structure that contains UUIDs for set of groups in a foreign cell and the UUID that identifies the foreign cell. The sec_id_foreign_groupset_t data type is composed of the following elements: realm A value of type sec_id_t that contain the UUID of the foreign cell. num_groups An unsigned 16-bit integer specifying the number of group UUIDs in groups. groups A printer to a sec_id_t that contains the UUIDs of the groupset from the foreign cell. CONSTANTS The following constants are used in the Extended Privilege Attribute calls and in the the sec_login calls that implement extended privilege attributes: sec_id_compat_mode_none Compatibility mode is off. sec_id_compat_mode_initiator Compatibility mode is on. The 1.0 PAC data extracted from the EPAC of the chain initiator. sec_id_compat_mode_caller Compatibility mode is on. The 1.0 PAC data extracted from the last delegate in the delegation chain. sec_id_deleg_type_none Delegation is not allowed. sec_id_deleg_type_traced Traced delegation is allowed. sec_id_deleg_type_impersonation Simple (impersonation) delegation is allowed. sec_rstr_e_type_user The delegation target is a local principal identified by UUID. This type conforms with the POSIX 1003.6 standard. sec_rstr_e_type_group The delegation target is a local group identified by UUID. This type conforms with the POSIX 1003.6 standard. sec_rstr_e_type_foreign_user The delegation target is a foreign principal identified by principal and cell UUID. sec_rstr_e_type_foreign_group The delegation target is a foreign group identified by group and cell UUID. sec_rstr_e_type_foreign_other The delegation target is any principal that can authenticate to the foreign cell identified by UUID. sec_rstr_e_type_any_other The delegation target is any principal that can authenticate to any cell, but is not identified in any other type entry. sec_rstr_e_type_no_other No principal can act as a target or delegate. FILES SYS$COMMON:[DCE$LIBRARY]SEC_CRED.IDL The idl file from which sec_cred.h was derived. SYS$COMMON:[DCE$LIBRARY]ID_EPAC.IDL The idl file from which id_epac.h was derived. SYS$COMMON:[DCE$LIBRARY]NBASE.IDL The idl file from which nbase.h was derived. 4 ACL_API_DATA_TYPES SYNOPSIS #include Data Types The following data types are used in sec_acl_ calls: sec_acl_handle_t A pointer to an opaque handle bound to an ACL that is the subject of a test or examination. The handle is bound to the ACL with sec_acl_bind(). An unbound handle has the value sec_acl_default_handle. sec_acl_posix_semantics_t A flag that indicates which, if any, POSIX ACL semantics an ACL manager supports. The following constants are defined for use with the sec_acl_posix_semantics_t data type: sec_acl_posix_no_semantics The manager type does not support POSIX semantics. sec_acl_posix_mask_obj The manager type supports the mask_obj entry type and POSIX 1003.6 Draft 12 ACL mask entry semantics. sec_acl_t This data type is the fundamental type for the ACL manager interfaces. The sec_acl_t type contains a complete access control list, made up of a list of entry fields (type sec_acl_entry_t). The default cell identifies the authentication authority for simple ACL entries (foreign entries identify their own foreign cells). The sec_acl_manager_type identifies the manager to interpret this ACL. The sec_acl_t type is a structure containing the following fields: default_realm A structure of type sec_acl_id_t, this identifies the UUID and (optionally) the name of the default cell. sec_acl_manager_type Contains the UUID of the ACL manager type. num_entries An unsigned 32-bit integer containing the number of ACL entries in this ACL. sec_acl_entries An array containing num_entries pointers to different ACL entries, each of type sec_acl_entry_t. sec_acl_p_t This data type, simply a pointer to a sec_acl_t, is for use with the sec_acl_list_t data type. sec_acl_list_t This data type is a structure containing an unsigned 32-bit integer num_acls that describes the number of ACLs indicated by its companion array of pointers, sec_acls, of type sec_acl_p_t. sec_acl_entry_t The sec_acl_entry_t type is a structure made up of the following components: perms A set of flags of type sec_acl_permset_t that describe the permissions granted for the principals identified by this ACL entry. Note that if a principal matches more than one ACL entry, the effective permissions will be the most restrictive combination of all the entries. entry_info A structure containing two members: entry_type A flag of type sec_acl_entry_type_t, indicating the type of ACL entry. tagged_union A tagged union whose contents depend on the type of the entry. The types of entries indicated by entry_type can be the following: sec_acl_e_type_user_obj The entry contains permissions for the implied user object. This type is described in the POSIX 1003.6 standard. sec_acl_e_type_group_obj The entry contains permissions for the implied group object. This type is described in the POSIX 1003.6 standard. sec_acl_e_type_other_obj The entry contains permissions for principals not otherwise named through user or group entries. This type is described in the POSIX 1003.6 standard. sec_acl_e_type_user The entry contains a key that identifies a user. This type is described in the POSIX 1003.6 standard. sec_acl_e_type_group The entry contains a key that identifies a group. This type is described in the POSIX 1003.6 standard. sec_acl_e_type_mask_obj The entry contains the maximum permissions for all entries other than mask_obj, unauthenticated, user_obj, other_obj. sec_acl_e_type_foreign_user The entry contains a key that identifies a user and the foreign realm. sec_acl_e_type_foreign_group The entry contains a key that identifies a group and the foreign realm. sec_acl_e_type_foreign_other The entry contains a key that identifies a foreign realm. Any user that can authenticate to the foreign realm will be allowed access. sec_acl_e_type_any_other The entry contains permissions to be applied to any accessor who can authenticate to any realm, but is not identified in any other entry (except sec_acl_e_type_unauthenticated). sec_acl_e_type_unauthenticated The entry contains permissions to be applied when the accessor does not pass authentication procedures. A privilege attribute certificate will indicate that the caller's identity is not authenticated. The identity is used to match against the standard entries, but the access rights are masked by this mask. If this mask does not exist in an ACL, the ACL is assumed to grant no access and all unauthenticated access attempts will be denied. Great care should be exercised when allowing unauthenticated access to an object. Almost by definition, unauthenticated access is very easy to spoof. The presence of this mask on an ACL essentially means that anyone can get at least as much access as allowed by the mask. sec_acl_e_type_extended The entry contains additional "pickled" data. This kind of entry cannot be interpreted, but can be used by an out-of-date client when copying an ACL from one manager to another (assuming that the two managers each understand the data). The contents of the tagged union depend on the entry type. For the following entry types, the union contains a UUID and an optional print string (called entry_info.tagged_union.id with type sec_id_t) for an identified local principal, or for an identified foreign realm. + sec_acl_e_type_user + sec_acl_e_type_group + sec_acl_type_foreign_other For the following entry types, the union contains two UUIDs and optional print strings (called entry_info.tagged_union.foreign_id with type sec_id_foreign_t) for an identified foreign principal and its realm. + sec_acl_e_type_foreign_user + sec_acl_e_type_foreign_group For an extended entry (sec_acl_e_type_extended), the union contains entry_info.tagged_union.extended_info, a pointer to an information block of type sec_acl_extend_info_t. sec_acl_permset_t A 32-bit set of permission flags. The flags currently represent the conventional file system permissions (read, write, execute) and the extended DFS permissions (owner, insert, delete). The "unused" flags represent permissions that can only be interpreted by the manager for the object. For example, sec_acl_perm_unused_00000080 may mean to one ACL manager that withdrawals are allowed, and to another ACL manager that rebooting is allowed. The following constants are defined for use with the sec_acl_permset_t data type: sec_acl_perm_read The ACL allows read access to the protected object. sec_acl_perm_write The ACL allows write access to the protected object. sec_acl_perm_execute The ACL allows execute access to the protected object. sec_acl_perm_control The ACL allows the ACL itself to be modified. sec_acl_perm_insert The ACL allows insert access to the protected object. sec_acl_perm_delete The ACL allows delete access to the protected object. sec_acl_perm_test The ACL allows access to the protected object only to the extent of being able to test for existence. The bits from 0x00000080 to 0x80000000 are not used by the conventional ACL permission set. Constants of the form sec_acl_perm_unused_00000080 have been defined so application programs can easily use these bits for extended ACLs. sec_acl_extend_info_t This is an extended information block, provided for future extensibility. Primarily, this allows an out-of-date client to read an ACL from a newer manager and apply it to another (up-to- date) manager. The data cannot be interpreted by the out-of-date client without access to the appropriate "pickling" routines (that presumably are unavailable to such a client). In general, ACL managers should not accept ACLs that contain entries the manager does not understand. The manager clearly cannot perform the security service requested by an uninterpretable entry, and it is considered a security breach to lead a client to believe that the manager is performing a particular class of service if the manager cannot do so. The data structure is made up of the following components: extension_type The UUID of the extension type. format_label The format of the label, in ndr_format_t form. num_bytes An unsigned 32-bit integer indicating the number of bytes containing the "pickled" data. pickled_data The byte array containing the "pickled" data. sec_acl_type_t The sec_acl_type_t type differentiates among the various types of ACLs an object can possess. Most file system objects will only have one ACL controlling the access to that object, but objects that control the creation of other objects (sometimes referred to as "containers") may have more. For example, a directory can have three different ACLs: the directory ACL, controlling access to the directory; the initial object (or default object) ACL, which serves as a mask when creating new objects in the directory; and the initial directory (or default directory) ACL, which serves as a mask when creating new directories (containers). The sec_acl_type_t is an enumerated set containing one of the following values: sec_acl_type_object The ACL refers to the specified object. sec_acl_type_default_object The ACL is to be used when creating objects in the container. sec_acl_type_default_container The ACL is to be used when creating nested containers. The following values are defined but not currently used. They are available for application programs that may create an application- specific ACL definition. sec_acl_type_unspecified_3 sec_acl_type_unspecified_4 sec_acl_type_unspecified_5 sec_acl_type_unspecified_6 sec_acl_type_unspecified_7 sec_acl_printstring_t A sec_acl_printstring_t structure contains a printable representa- tion for a permission in a sec_acl_permset_t permission set. This allows a generic ACL editing tool to be used for application- specific ACLs. The tool need not know the printable representation for each permission bit in a given permission set. The sec_acl_get_printstring() function will query an ACL manager for the print strings of the permissions it supports. The structure consists of three components: printstring A character string of maximum length sec_acl_printstring_len describing the printable representation of a specified permission. helpstring A character string of maximum length sec_acl_printstring_help_len containing some text that may be used to describe the specified permission. permissions A sec_acl_permset_t permission set describing the permissions that will be represented with the specified print string. sec_acl_component_name_t This type is a pointer to a character string, to be used to specify the entity a given ACL is protecting. CONSTANTS The following constants are used in sec_acl_ calls: sec_acl_default_handle The value of an unbound ACL manager handle. sec_rgy_acct_key_t Constants The following 32-bit integer constants are used with the sec_rgy_acct_key_t data type: sec_rgy_acct_key_none Invalid key. sec_rgy_acct_key_person The person name alone is enough. sec_rgy_acct_key_group The person and group names are both necessary for the account abbreviation. sec_rgy_acct_key_org The person, group, and organization names are all necessary. sec_rgy_acct_key_last Key values must be less than this constant. sec_rgy_pname_t_size The maximum number of characters in a sec_rgy_pname_t. sec_acl_permset_t Constants The following constants are defined for use with the sec_acl_permset_t data type: sec_acl_perm_read The ACL allows read access to the protected object. sec_acl_perm_write The ACL allows write access to the protected object. sec_acl_perm_execute The ACL allows execute access to the protected object. sec_acl_perm_owner The ACL allows owner-level access to the protected object. sec_acl_perm_insert The ACL allows insert access to the protected object. sec_acl_perm_delete The ACL allows delete access to the protected object. sec_acl_perm_test The ACL allows access to the protected object only to the extent of being able to test for existence. sec_acl_perm_unused_00000080 - sec_acl_perm_unused_0x80000000 The bits from 0x00000080 to 0x80000000 are not used by the conventional ACL permission set. Constants have been defined so application programs can easily use these bits for extended ACLs. sec_acl_printstring_len The maximum length of the printable representation of an ACL permis- sion. (See sec_acl_printstring_t.) sec_acl_printstring_help_len The maximum length of a help message to be associated with a supported ACL permission. (See sec_acl_printstring_t.) FILES SYS$COMMON:[DCE$LIBRARY]ACLBASE.IDL The idl file from which aclbase.h was derived. 4 KEY_MANAGEMENT_API_DATA_TYPES NOTES Key management operations that take a keydata argument expect a pointer to a sec_passwd_rec_t structure, and those that take a keytype argument (void *) expect a pointer to a sec_passwd_type_t. Key management operations that yield a keydata argument as output set the pointer to an array of sec_passwd_rec_t. (The array is terminated by an element with a key type of sec_passwd_none.) Operations that take a keydata argument expect a pointer to a sec_passwd_rec_t structure. Operations that yield a keydata argument as output set the pointer to an array of sec_passwd_rec_t. (The array is terminated by an element with key type sec_passwd_none.) Operations that take a keytype argument (void *) expect a pointer to a sec_passwd_type_t. SYNOPSIS #include DATA TYPES An enumerated set describing the currently supported key types. The possible values are: Indicates no key types are supported. Indicates that the key is a printable string of data. Indicates that the key is DES encrypted data. sec_passwd_rec_t A structure containing either a plaintext password or a preencrypted buffer of password data. The sec_passwd_rec_t structure consists of three components: version_number The version number of the password. pepper A character string combined with the password before an encryption key is derived from the password. key A structure consists of the following components: key_type The key type can be the following: sec_passwd_plain Indicates that a printable string of data is stored in plain. sec_passwd_des Indicates that an array of data is stored in des_key. tagged_union A structure specifying the password. The value of the structure depends on key_type. If key_type is sec_passwd_plain, structure contains plain, a character string. If key_type is sec_passwd_des, the structure contains des_key, a DES key of type sec_passwd_des_key_t. sec_passwd_version_t An unsigned 32-bit integer that defines the password version number. You can supply a version number or a 0 for no version number. If you supply the constant sec_passwd_c_version_none, the Security service supplies a system-generated version number. A 32-bit unsigned integer whose purpose is to indicate the authenti- cation service in use, since a server may have different keys for different levels of security. The possible values of this data type and their meanings are as follows: rpc_c_authn_none No authentication. rpc_c_authn_dce_private DCE private key authentication (an implementation of the Kerberos system). rpc_c_authn_dce_public DCE public key authentication (reserved for future use). Constants There are no constants specially defined for use with the key management API. FILES SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL The idl file from which keymgmt.h was derived. 4 ID_MAPPING_API_DATA_TYPES SYNOPSIS #include DATA TYPES No special data types are defined for the ID Mapping API. CONSTANTS No special constants are defined for the ID Mapping API. FILES SYS$COMMON:[DCE$LIBRARY]SECIDMAP.IDL The idl file from which secidmap.h was derived. 4 PASSWORD_MANAGEMENT_API_DATA_TYPES SYNOPSIS #include DATA TYPES The following data types are used in sec_pwd_mgmt_ calls: A pointer to an opaque handle consisting of password management information about a principal. It is returned by sec_pwd_mgmt_setup(). CONSTANTS There are no constants specially defined for use with the Password Management API. FILES SYS$COMMON:[DCE$LIBRARY]SEC_PWD_MGMT.IDL The idl file from which sec_pwd_mgmt.h was derived. 3 API_Routines 4 rdacl_get_access NAME rdacl_get_access - Reads a privilege attribute certificate SYNOPSIS #include void rdacl_get_access( handle_t h, sec_acl_component_name_t component_name, uuid_t *manager_type, sec_acl_permset_t *net_rights, error_status_t *status); PARAMETERS Input h A handle referring to the object whose ACL is to be accessed. component_name A character string containing the name of the target object. manager_type A pointer to the UUID identifying the type of the ACL manager in question. There may be more than one type of ACL manager protecting the object whose ACL is bound to the input handle. Use this parameter to distinguish them. Use sec_acl_get_manager_types() to acquire a list of the manager types protecting a given object. Output net_rights The output list of access rights, in sec_acl_permset_t form. This is a 32-bit set of permission flags supported by the manager type. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The rdacl_get_access() routine determines the complete extent of access to the specified object by the calling process. Although the rdacl_test_access() routines are the preferred method of testing access, this routine is useful for implementing operations like the conventional UNIX access function. NOTES This call is not intended to be used by application programs. The sec_acl Application Programming Interface (API) provides all the functionality necessary to use the ACL facility. This reference page is provided for programmers who wish to write an ACL manager. In order to write an ACL manager, a programmer must implement the entire rdacl interface. This network interface is called on the client side via the sec_acl local interface. Developers are responsible for implementing the server side of this interface. Test server code is included as a sample implementation. FILES SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL The idl file from which dce/rdaclif.h was derived. ERRORS sec_acl_invalid_manager_type The manager type is not valid. sec_acl_invalid_acl_type The ACL type is not valid. sec_acl_not_authorized The requested operation is not allowed. sec_acl_object_not_found The requested object could not be found. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro rdacl_test_access 4 rdacl_get_manager_types NAME rdacl_get_manager_types - Lists the types of ACLs protecting an object SYNOPSIS #include void rdacl_get_manager_types( handle_t h, sec_acl_component_name_t component_name, sec_acl_type_t sec_acl_type, unsigned32 size_avail, unsigned32 *size_used, unsigned32 *num_types, uuid_t manager_types[], error_status_t *status); PARAMETERS Input h A handle referring to the target object. component_name A character string containing the name of the target object. sec_acl_type The ACL type. The sec_acl_type_t data type distinguishes the various types of ACLs an object can possess for a given manager type. The possible values are as follows: + sec_acl_type_object + sec_acl_type_default_object + sec_acl_type_default_container size_avail An unsigned 32-bit integer containing the allocated length of the manager_types[] array. Output size_used An unsigned 32-bit integer containing the number of output entries returned in the manager_types[] array. num_types An unsigned 32-bit integer containing the number of types returned in the manager_types[] array. This is always equal to size_used. manager_types[] An array of length size_avail to contain UUIDs (of type uuid_t) identifying the different types of ACL managers protecting the target object. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The rdacl_get_manager_types() routine returns a list of the types of ACLs protecting an object. For example, in addition to the regular file system ACL, a file representing the stable storage of some database could have an ACL manager that supported permissions allowing database updates only on certain days of the week. ACL editors and browsers can use this operation to determine the ACL manager types that a particular reference monitor is using to protect a selected entity. Then, using the rdacl_get_printstring() routine, they can determine how to format for display the permissions supported by a specific manager. NOTES This call is not intended to be used by application programs. The sec_acl Application Programming Interface (API) provides all the functionality necessary to use the ACL facility. This reference page is provided for programmers who wish to write an ACL manager. In order to write an ACL manager, a programmer must implement the entire rdacl interface. This network interface is called on the client side via the sec_acl local interface. Developers are responsible for implementing the server side of this interface. Test server code is included as a sample implementation. FILES SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL The idl file from which dce/rdaclif.h was derived. ERRORS error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro rdacl_get_printstring 4 rdacl_get_mgr_types_semantics NAME rdacl_get_manager_types_semantics - Lists the ACL manager types protecting an object and the POSIX semantics supported by each manager type SYNOPSIS #include void rdacl_get_mgr_types_semantics( handle_t h, sec_acl_component_name_t component_name, sec_acl_type_t sec_acl_type, unsigned32 size_avail, unsigned32 *size_used, unsigned32 *num_types, uuid_t manager_types[], sec_acl_posix_semantics_t posix_semantics[], error_status_t *status); PARAMETERS Input h A handle referring to the target object. component_name A character string containing the name of the target object. sec_acl_type The ACL type used to limit the function's output to ACL managers that control the specified types of ACLs. The possible values are as follows: + sec_acl_type_object - Object ACL, the ACL controlling access to an object. + sec_acl_type_default_object - Initial Object ACL, the default ACL for objects created in a container object. + sec_acl_type_default_container - Initial Container ACL, the default ACL for containers created in a container object. size_avail An unsigned 32-bit integer containing the allocated length of the manager_types[] and the posix_semantics[] arrays. Output size_used An unsigned 32-bit integer containing the number of output entries returned in the manager_types[] array. num_types An unsigned 32-bit integer containing the number of types returned in the manager_types[] array. This is always equal to size_used. manager_types[] An array of length size_avail containing the returned UUIDs (of type uuid_t) identifying the different ACL manager types protecting the target object. posix_semantics[] An array of length size_avail containing the POSIX semantics (of type sec_acl_posix_semantics_t) that are supported by each returned ACL manager type. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The rdacl_get_manager_types_semantics() routine returns a list of the ACL manager types protecting an object and a list of the POSIX semantics supported by those ACL manager types. Access to an object can be controlled by multiple ACL manager types. For example, access to a file representing the stable storage of a database could be controlled by two ACL manager types each with completely different sets of permissions: one to provide standard file system access (read, write, execute, etc.) and one to provide access that allows database updates only on certain days of the week. ACL editors and browsers can use this operation to determine the ACL manager types that a particular reference monitor is using to protect a selected entity. Then, using the rdacl_get_printstring() routine, they can determine how to format for display the permissions supported by a specific manager. NOTES This call is not intended to be used by application programs. The sec_acl Application Programming Interface (API) provides all the functionality necessary to use the ACL facility. This reference page is provided for programmers who wish to write an ACL manager. In order to write an ACL manager, a programmer must implement the entire rdacl interface. This network interface is called on the client side via the sec_acl local interface. Developers are responsible for implementing the server side of this interface. Test server code is included as a sample implementation. FILES SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL The idl file from which dce/rdaclif.h was derived. ERRORS error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro rdacl_get_printstring 4 rdacl_get_printstring NAME rdacl_get_printstring - Returns printable ACL strings SYNOPSIS #include void rdacl_get_printstring( handle_t h, uuid_t *manager_type, unsigned32 size_avail, uuid_t *manager_type_chain, sec_acl_printstring_t *manager_info, boolean32 *tokenize, unsigned32 *total_num_printstrings, unsigned32 *size_used, sec_acl_printstring_t printstrings[], error_status_t *status); PARAMETERS Input h A handle referring to the target object. manager_type A pointer to the UUID identifying the type of the ACL manager in question. There may be more than one type of ACL manager protecting the object whose ACL is bound to the input handle. Use this parameter to distinguish them. Use rdacl_get_manager_types() to acquire a list of the manager types protecting a given object. size_avail An unsigned 32-bit integer containing the allocated length of the printstrings[] array. Output manager_type_chain If the target object ACL contains more than 32 permission bits, multiple manager types are used, one for each 32-bit wide "slice" of permissions. The UUID returned in manager_type_chain refers to the next ACL manager in the chain. If there are no more ACL managers for this ACL, uuid_nil is returned. manager_info Provides a name and helpstring for the given ACL manager. tokenize When FALSE this variable indicates that the returned permission printstrings are unambiguous and therefore may be concatenated when printed without confusion. When TRUE, however, this property does not hold, and the strings need to be separated when printed or passed. total_num_printstrings An unsigned 32-bit integer containing the total number of permission printstrings supported by this ACL manager type. size_used An unsigned 32-bit integer containing the number of permission entries returned in the printstrings[] array. printstrings[] An array of permission printstrings of type sec_acl_printstring_t. Each entry of the array is a structure containing three components: printstring A character string of maximum length sec_acl_printstring_len containing the printable representation of a specified permission. helpstring A character string of maximum length sec_acl_printstring_help_len containing some text that can be used to describe the specified permission. permissions A sec_acl_permset_t permission set describing the permissions that are to be represented with the companion printstring. The array consists of one such entry for each permission supported by the ACL manager identified by manager_type. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The rdacl_get_printstring() routine returns an array of printable representations (called printstrings) for each permission bit or combination of permission bits the specified ACL manager will support. The ACL manager type specified must be one of the types indicated by the ACL handle. In addition to returning the printstrings, this routine also returns instructions about how to print the strings. When the tokenize variable is set to FALSE, a print string might be r or w, which could be concatenated in the display as rw without any confusion. However, when the tokenize variable is TRUE, it implies the printstrings might be of a form like read or write, which must be displayed separated by spaces or colons or something. In any list of permission printstrings, there may appear to be some redundancy. ACL managers often define aliases for common permission combinations. By convention, however, simple entries need to appear at the beginning of the printstrings[] array, and combinations need to appear at the end. NOTES This call is not intended to be used by application programs. The sec_acl Application Programming Interface (API) provides all the functionality necessary to use the ACL facility. This reference page is provided for programmers who wish to write an ACL manager. In order to write an ACL manager, a programmer must implement the entire rdacl interface. This network interface is called on the client side via the sec_acl local interface. Developers are responsible for implementing the server side of this interface. Test server code is included as a sample implementation. FILES SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL The idl file from which dce/rdaclif.h was derived. ERRORS sec_acl_unknown_manager_type The manager type selected is not among those referenced by the input handle. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_acl_bind rdacl_get_manager_types 4 rdacl_get_referral NAME rdacl_get_referral - Gets a referral to an ACL update site SYNOPSIS #include void rdacl_get_referral( handle_t h, sec_acl_component_name_t component_name, uuid_t *manager_type, sec_acl_type_t sec_acl_type, sec_acl_tower_set_t *towers[], error_status_t *status); PARAMETERS Input h A handle referring to the target object. component_name A character string containing the name of the target object. manager_type A pointer to the UUID identifying the type of the ACL manager in question. There may be more than one type of ACL manager protecting the object whose ACL is bound to the input handle. Use this parameter to distinguish them. Use sec_acl_get_manager_types() to acquire a list of the manager types protecting a given object. sec_acl_type The ACL type. The sec_acl_type_t data type distinguishes the various types of ACLs an object can possess for a given manager type. The possible values are as follows: + sec_acl_type_object + sec_acl_type_default_object + sec_acl_type_default_container Output towers[] A pointer to address information indicating an ACL update site. This information, obtained from the RPC runtime, is used by the client-side code to construct a new ACL binding handle indicating a site that will not return the sec_acl_site_readonly error. The sec_acl_tower_set_t structure contains an array of towers (called towers[]) and an unsigned 32-bit integer indicating the number of array elements (called count). This type enables the client to pass in an unallocated array of towers and have the server allocate the correct amount. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The rdacl_get_referral() routine obtains a referral to an ACL update site. This function is used when the current ACL site yields a sec_acl_site_readonly error. Some replication managers will require all updates for a given object to be directed to a given replica. If clients of the generic ACL interface know they are dealing with an object that is replicated in this way, this function allows them to recover from the problem and rebind to the proper update site. The DCE network registry, for example, is replicated this way. NOTES This call is not intended to be used by application programs. The sec_acl Application Programming Interface (API) provides all the functionality necessary to use the ACL facility. This reference page is provided for programmers who wish to write an ACL manager. In order to write an ACL manager, a programmer must implement the entire rdacl interface. This network interface is called on the client side via the sec_acl local interface. Developers are responsible for implementing the server side of this interface. Test server code is included as a sample implementation. FILES SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL The idl file from which dce/rdaclif.h was derived. ERRORS sec_acl_unknown_manager_type The manager type selected is not an available option. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro 4 rdacl_lookup NAME rdacl_lookup - Returns the ACL for an object SYNOPSIS #include void rdacl_lookup( handle_t h, sec_acl_component_name_t component_name, uuid_t *manager_type, sec_acl_type_t sec_acl_type, sec_acl_result_t *result); PARAMETERS Input h A handle referring to the target object. component_name A character string containing the name of the target object. manager_type A pointer to the UUID identifying the type of the ACL manager in question. There may be more than one type of ACL manager protecting the object whose ACL is bound to the input handle. Use this parameter to distinguish them. Use sec_acl_get_manager_types() to acquire a list of the manager types protecting a given object. sec_acl_type The ACL type. The sec_acl_type_t data type distinguishes the various types of ACLs an object can possess for a given manager type. The possible values are as follows: + sec_acl_type_object + sec_acl_type_default_object + sec_acl_type_default_container Output result A pointer to a tagged union of type sec_acl_result_t. The tag is the completion status, result.st. If result.st is equal to error_status_ok, the union contains an ACL. Otherwise, the completion status indicates an error, and the union is empty. If the call returned successfully, the result.tagged_union.sec_acl_list_t structure contains a sec_acl_list_t. This data type is an array of pointers to sec_acl_ts that define ACLs. If the permission set of the returned ACL is 32 bits or smaller, sec_acl_list_t points to only one sec_acl_t. If the permission set of the returned ACL is larger than 32 bits, multiple sec_acl_ts are used to hold them, and the sec_acl_list_t points to multiple sec_acl_ts. DESCRIPTION The rdacl_lookup() routine loads into memory a copy of an object's ACL corresponding to the specified manager type. The routine returns a pointer to the ACL. This routine is only used by ACL editors and browsers; an application would use sec_acl_test_access() or sec_acl_test_access_on_behalf() to process the contents of an ACL. NOTES This call is not intended to be used by application programs. The sec_acl Application Programming Interface (API) provides all the functionality necessary to use the ACL facility. This reference page is provided for programmers who wish to write an ACL manager. In order to write an ACL manager, a programmer must implement the entire rdacl interface. This network interface is called on the client side via the sec_acl local interface. Developers are responsible for implementing the server side of this interface. Test server code is included as a sample implementation. FILES SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL The idl file from which dce/rdaclif.h was derived. ERRORS sec_acl_unknown_manager_type The manager type selected is not an available option. sec_acl_cant_allocate_memory The requested operation requires more memory than is avail- able. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_acl_bind sec_acl_test_access sec_acl_test_access_on_behalf 4 rdacl_replace NAME rdacl_replace - Replaces an ACL SYNOPSIS #include void rdacl_replace( handle_t h, sec_acl_component_name_t component_name, uuid_t *manager_type, sec_acl_type_t sec_acl_type, sec_acl_list_t *sec_acl_list, error_status_t *status); PARAMETERS Input h A handle referring to the target object. component_name A character string containing the name of the target object. manager_type A pointer to the UUID identifying the type of the ACL manager in question. There may be more than one type of ACL manager protecting the object whose ACL is bound to the input handle. Use this parameter to distinguish them. Use sec_acl_get_manager_types() to acquire a list of the manager types protecting a given object. sec_acl_type The ACL type. The sec_acl_type_t data type distinguishes the various types of ACLs an object can possess for a given manager type. The possible values are as follows: + sec_acl_type_object + sec_acl_type_default_object + sec_acl_type_default_container sec_acl_list The new ACL to use for the target object. This is represented by a pointer to the sec_acl_list_t structure containing the complete Access Control List. An ACL contains a list of ACL entries, the UUID of the default cell where authentication takes place (foreign entries in the ACL contain the name of their parent cell), and the UUID of the ACL manager to interpret the list. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The rdacl_replace() routine replaces the ACL indicated by the input handle with the information in the sec_acl_list parameter. ACLs are thought of as immutable, and in order to modify them, an editing application must read an entire ACL (using the sec_acl_lookup() routine), modify it as needed, and replace it using this routine. NOTES This call is not intended to be used by application programs. The sec_acl Application Programming Interface (API) provides all the functionality necessary to use the ACL facility. This reference page is provided for programmers who wish to write an ACL manager. In order to write an ACL manager, a programmer must implement the entire rdacl interface. This network interface is called on the client side via the sec_acl local interface. Developers are responsible for implementing the server side of this interface. Test server code is included as a sample implementation. FILES SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL The idl file from which dce/rdaclif.h was derived. ERRORS sec_acl_unknown_manager_type The manager type selected is not an available option. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_acl_bind sec_acl_lookup 4 rdacl_test_access NAME rdacl_test_access - Tests access to an object SYNOPSIS #include boolean32 rdacl_test_access( handle_t h, sec_acl_component_name_t component_name, uuid_t *manager_type, sec_acl_permset_t desired_permset, error_status_t *status); PARAMETERS Input h A handle referring to the target object. component_name A character string containing the name of the target object. manager_type A pointer to the UUID identifying the type of the ACL manager in question. There may be more than one type of ACL manager protecting the object whose ACL is bound to the input handle. Use this parameter to distinguish them. Use sec_acl_get_manager_types() to acquire a list of the manager types protecting a given object. desired_permset A permission set in sec_acl_permset_t form containing the desired privileges. This is a 32-bit set of permission flags supported by the manager type. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The rdacl_test_access() routine determines if the specified ACL contains entries granting privileges to the calling process matching those in desired_permset. An application generally only inquires after the minimum set of privileges needed to accomplish a specific task. NOTES This call is not intended to be used by application programs. The sec_acl Application Programming Interface (API) provides all the functionality necessary to use the ACL facility. This reference page is provided for programmers who wish to write an ACL manager. In order to write an ACL manager, a programmer must implement the entire rdacl interface. This network interface is called on the client side via the sec_acl local interface. Developers are responsible for implementing the server side of this interface. Test server code is included as a sample implementation. FILES SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL The idl file from which dce/rdaclif.h was derived. ERRORS sec_acl_unknown_manager_type The manager type selected is not an available option. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro rdacl_test_access_on_behalf 4 rdacl_test_access_on_behalf NAME rdacl_test_access_on_behalf - Tests access to an object on behalf of another process SYNOPSIS #include boolean rdacl_test_access_on_behalf( handle_t h, sec_acl_component_name_t component_name, uuid_t *manager_type, sec_id_pac_t *subject, sec_acl_permset_t desired_permset, error_status_t *status); PARAMETERS Input h A handle referring to the target object. component_name A character string containing the name of the target object. manager_type A pointer to the UUID identifying the type of the ACL manager in question. There may be more than one type of ACL manager protecting the object whose ACL is bound to the input handle. Use this parameter to distinguish them. Use sec_acl_get_manager_types() to acquire a list of the manager types protecting a given object. subject A Privilege Attribute Certificate (PAC) for the subject process. The PAC contains the name and UUID of the principal and parent cell of the subject process, as well as a list of any groups to which it belongs. The PAC also contains a flag (named authenticated). When set, it indicates that the certificate was obtained from an authenticated source. When not set, the certificate must not be trusted. (The field is FALSE when it was obtained from the rpc_auth layer and the protect level was set to rpc_c_protect_level_none. This indicates that no authentication protocol was actually used in the remote procedure call; the identity was simply transmitted from the caller to the callee. If an authentication protocol was used, then the flag is set to TRUE.) A server uses rpc_binding_inq_auth_client() to acquire a certificate for the client process. desired_permset A permission set in sec_acl_permset_t form containing the desired privileges. This is a 32-bit set of permission flags supported by the manager type. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The rdacl_test_access_on_behalf() routine determines if the specified ACL contains entries granting privileges to the subject, a process besides the calling process, matching those in desired_permset. This routine succeeds only if the access is available to both the caller process as well as the subject identified in the call. An application will generally only inquire after the minimum set of privileges needed to accomplish a specific task. NOTES This call is not intended to be used by application programs. The sec_acl Application Programming Interface (API) provides all the functionality necessary to use the ACL facility. This reference page is provided for programmers who wish to write an ACL manager. In order to write an ACL manager, a programmer must implement the entire rdacl interface. This network interface is called on the client side via the sec_acl local interface. Developers are responsible for implementing the server side of this interface. Test server code is included as a sample implementation. FILES SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL The idl file from which dce/rdaclif.h was derived. ERRORS sec_acl_unknown_manager_type The manager type selected is not an available option. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro rdacl_test_access rpc_binding_inq_auth_client 4 sec_acl_bind NAME sec_acl_bind - Returns a handle for an object's ACL SYNOPSIS #include void sec_acl_bind( unsigned char *entry_name, boolean32 bind_to_entry, sec_acl_handle_t *h, error_status_t *status); PARAMETERS Input entry_name The name of the target object. Subsequent ACL operations using the returned handle will affect the ACL of this object. bind_to_entry Bind indicator, for use when entry_name identifies both an entry in the global namespace and an actual object. A TRUE value binds the handle to the entry in the namespace, while FALSE binds the handle to the actual object. Output h A pointer to the sec_acl_handle_t variable to receive the returned ACL handle. The other sec_acl routines use this handle to refer to the ACL for the object specified with entry_name. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_acl_bind() routine returns a handle bound to the indicated object's ACL. This routine is central to all the other sec_acl routines, each of which requires this handle to identify the ACL on which to operate. NOTES If the specified name is both an actual object, and an entry in the global namespace, there are two ACLs associated with it. For example, in addition to the ACL normally attached to file system objects, the root directory of a file system has an ACL corresponding to its entry in the global namespace. This controls access by outsiders to the entire file system, whereas the resident ACL for the root directory only controls access to the directory and, by inheritance, its sub- directories. The ambiguity must be resolved with the bind_to_entry parameter. FILES SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL The idl file from which dce/daclif.h was derived. ERRORS sec_acl_object_not_found The requested object could not be found. sec_acl_no_acl_found There is no ACL associated with the specified object. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro 4 sec_acl_bind_to_addr NAME sec_acl_bind_to_addr - Returns a handle to an object identified by its network address SYNOPSIS #include void sec_acl_bind_to_addr( unsigned char *site_addr, sec_acl_component_name_t component_name, sec_acl_handle_t *h, error_status_t *status); PARAMETERS Input site_addr An RPC string binding to the fully qualified network address of the target object. component_name The name of the target object. Subsequent ACL operations using the returned handle will affect the ACL of this object. Output h A pointer to the sec_acl_handle_t variable to receive the returned ACL handle. The other sec_acl routines use this handle to refer to the ACL for the object specified with entry_name. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_acl_bind_to_addr() routine returns a handle bound to the indicated object's ACL manager. This routine and the sec_acl_bind() routine are central to all the other sec_acl routines, each of which requires a handle to identify the ACL on which to operate. This routine differs from sec_acl_bind() in that it binds to the network address of the target object, rather than to a cell namespace entry. Therefore, unlike sec_acl_bind(), it is possible to pass sec_acl_bind_to_addr() a null string as a component name and to bind with a nonexistent name. The purpose of this call is to eliminate the necessity of looking up an object's name. To validate the name, use sec_acl_bind(). FILES SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL The idl file from which dce/daclif.h was derived. ERRORS sec_acl_object_not_found The requested object could not be found. sec_acl_no_acl_found There is no ACL associated with the specified object. sec_acl_unable_to_authenticate The call could not authenticate to the server that manages the target object's ACL. sec_acl_bind_error The call could not bind to the requested site. sec_acl_invalid_site_name The site_addr parameter is invalid. sec_acl_cant_allocate_memory Memory allocation failure. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro 4 sec_acl_calc_mask NAME sec_acl_calc_mask - Returns the sec_acl_type_mask_obj entry for the specified ACL list SYNOPSIS #include void sec_acl_calc_mask( sec_acl_list_t *sec_acl_list, error_status_t *status); PARAMETERS Input/Output *sec_acl_list A pointer to a sec_acl_type_t the specifies the number of ACLs of each ACL type. The sec_acl_type_t data type distinguishes between the various types of ACLs an object can possess for a given manager. In the file system, for example, most objects have only one ACL, controlling the access to that object, but objects that control the creation of other objects (sometimes referred to as "containers") may have more. A directory, for example, can have ACLs to be used as initial values when member objects are created. Do not confuse ACL types with the permissions corresponding to different ACL manager types or with the ACL manager types them- selves. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_acl_calc_mask() routine calculates and sets the sec_acl_e_type_mask_obj entry of the specified ACL list. The value of the sec_acl_e_type_mask_obj entry is the union of the permissions of all ACL entries that refer to members of the File Group Class. This operation is performed locally, within the client. The function does not check to determine if the manager to which the specified ACL list will be submitted supports the sec_acl_e_type_mask_obj entry type. The calling application must determine whether to call this routine, after obtaining the required, if any, POSIX semantics, via the sec_acl_get_mgr_types_semantics() routine. NOTES This call is provided in source code form. FILES SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL The idl file from which dce/daclif.h was derived. ERRORS sec_acl_cant_allocate_memory Requested operation requires more memory than is available. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro 4 sec_acl_get_access NAME sec_acl_get_access - Lists the access (permission set) that the caller has for an object SYNOPSIS #include void sec_acl_get_access( sec_acl_handle_t h, uuid_t *manager_type, sec_acl_permset_t *net_rights, error_status_t *status); PARAMETERS Input h A handle referring to the object whose ACL is to be accessed. Use sec_acl_bind() to create this handle. manager_type A pointer to the UUID identifying the manager type of the ACL in question. There may be more than one type of ACL manager protecting the object whose ACL is bound to the input handle. Use this parameter to distinguish them. Use sec_acl_get_manager_types() to acquire a list of the manager types protecting a given object. Output net_rights The output list of access rights in sec_acl_permset_t form. This is a 32-bit set of permission flags supported by the manager type. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_acl_get_access() routine determines the complete extent of access to the specified object by the calling process. Although the sec_acl_test_access() and sec_acl_test_access_on_behalf() routines are the preferred method of testing access, this routine is useful for implementing operations like the conventional UNIX access function. Permissions Required The sec_acl_get_access() routine requires at least one permission of any kind on the object for which the access is to be returned. FILES SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL The idl file from which dce/daclif.h was derived. ERRORS error_status_ok The call was successful. RELATED INFORMATION Functions: sec_acl_test_access sec_acl_test_access_on_behalf 4 sec_acl_get_error_info NAME sec_acl_get_error_info - Returns error information from an ACL handle SYNOPSIS #include error_status_t sec_acl_get_error_info( sec_acl_handle_t h); PARAMETERS Input h A handle referring to the target ACL. The handle is bound to the ACL with the sec_acl_bind() routine, which also specifies the name of the object to which the target ACL belongs. DESCRIPTION The sec_acl_get_error_info() routine returns error information from the specified ACL handle. During a call to a routine in the sec_acl Application Programming Interface (API), error codes received from the RPC runtime or other APIs are saved in the ACL handle and a corresponding error code from the sec_acl set is passed back by the ACL API. The sec_acl_get_error_info() routine returns the last error code stored in the ACL handle for those clients who need to know exactly what went wrong. FILES SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL The idl file from which dce/daclif.h was derived. RETURN VALUES This routine returns a value of type error_status_t, indicating the cause of the last error issued by the RPC runtime. ERRORS sec_acl_invalid_handle The ACL handle specified by sec_acl_handle_t is invalid. RELATED INFORMATION Functions: sec_intro sec_acl_bind sec_acl_lookup 4 sec_acl_get_manager_types NAME sec_acl_get_manager_types - Lists the manager types of the ACLs protecting an object SYNOPSIS #include void sec_acl_get_manager_types( sec_acl_handle_t h, sec_acl_type_t sec_acl_type, unsigned32 size_avail, unsigned32 *size_used, unsigned32 *num_types, uuid_t manager_types[], error_status_t *status); PARAMETERS Input h A handle referring to the target object. Use sec_acl_bind() to create this handle. sec_acl_type The ACL type. The sec_acl_type_t data type distinguishes the various types of ACLs an object can possess for a given manager type. The possible values are as follows: + sec_acl_type_object + sec_acl_type_default_object + sec_acl_type_default_container size_avail An unsigned 32-bit integer containing the allocated length of the manager_types[] array. Output size_used An unsigned 32-bit integer containing the number of output entries returned in the manager_types[] array. num_types An unsigned 32-bit integer containing the number of types returned in the manager_types[] array. This may be greater than size_used if there was not enough space allocated in the manager_types[] array for all the manager types. manager_types[] An array of length size_avail to contain UUIDs (of type uuid_t) identifying the different types of ACL managers protecting the target object. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_acl_get_manager_types() routine returns a list of the manager types of ACLs of type sec_acl_type that are protecting the object identified by h. For example, in addition to the regular file system ACL, a file representing the stable storage of some database could have an ACL manager that supported permissions allowing database updates only on certain days of the week. ACL editors and browsers can use this operation to determine the ACL manager types that a particular reference monitor is using to protect a selected entity. Then, using the sec_acl_get_printstring() routine, they can determine how to format for display the permissions supported by a specific manager. Permissions Required The sec_acl_get_manager_types() routine requires at least one permission of any kind on the object for which the ACL manager types are to be returned. FILES SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL The idl file from which dce/daclif.h was derived. ERRORS error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_acl_bind sec_acl_get_printstring 4 sec_acl_get_manager_types_semantics NAME sec_acl_get_mgr_types_semantics - Lists the manager types of the ACLs protecting an object SYNOPSIS #include void sec_acl_get_mgr_types_semantics( sec_acl_handle_t h, sec_acl_type_t sec_acl_type, unsigned32 size_avail, unsigned32 *size_used, unsigned32 *num_types, uuid_t manager_types[], sec_acl_posix_semantics_t posix_semantics[], error_status_t *status); PARAMETERS Input h A handle referring to the target object. Use sec_acl_bind() to create this handle. sec_acl_type The ACL type. The sec_acl_type_t data type distinguishes the various types of ACLs an object can possess for a given manager type. The possible values are as follows: + sec_acl_type_object + sec_acl_type_default_object + sec_acl_type_default_container size_avail An unsigned 32-bit integer containing the allocated length of the manager_types[] array. Output size_used An unsigned 32-bit integer containing the number of output entries returned in the manager_types[] array. num_types An unsigned 32-bit integer containing the number of types returned in the manager_types[] array. This may be greater than size_used if there was not enough space allocated in the manager_types[] array for all the manager types. manager_types[] An array of length size_avail to contain UUIDs (of type uuid_t) identifying the different types of ACL managers protecting the target object. posix_semantics[] An array of POSIX semantics supported by each manager type with entries of type sec_acl_posix_semantics_t. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_acl_get_mgr_types_semantics() routine returns a list of the manager types of ACLs of type sec_acl_type that are protecting the object identified by h. For example, in addition to the regular file system ACL, a file representing the stable storage of some database could have an ACL manager that supported permissions allowing database updates only on certain days of the week. ACL editors and browsers can use this operation to determine the ACL manager types that a particular reference monitor is using to protect a selected entity. Then, using the sec_acl_get_printstring() routine, they can determine how to format for display the permissions supported by a specific manager. Permissions Required The sec_acl_get_mgr_types_semantics() routine requires at least one permission of any kind on the object for which the ACL manager types are to be returned. FILES SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL The idl file from which dce/daclif.h was derived. ERRORS error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_acl_bind sec_acl_get_printstring 4 sec_acl_get_printstring NAME sec_acl_get_printstring - Returns printable ACL strings SYNOPSIS #include void sec_acl_get_printstring( sec_acl_handle_t h, uuid_t *manager_type, unsigned32 size_avail, uuid_t *manager_type_chain, sec_acl_printstring_t *manager_info, boolean32 *tokenize, unsigned32 *total_num_printstrings, unsigned32 *size_used, sec_acl_printstring_t printstrings[], error_status_t *status); PARAMETERS Input h A handle referring to the target object. Use sec_acl_bind() to create this handle. manager_type A pointer to the UUID identifying the type of the ACL manager in question. There may be more than one type of ACL manager protecting the object whose ACL is bound to the input handle. Use this parameter to distinguish them. Use sec_acl_get_manager_types() to acquire a list of the manager types protecting a given object. size_avail An unsigned 32-bit integer containing the allocated length of the printstrings[] array. Output manager_type_chain If the target object ACL contains more than 32 permission bits, multiple manager types are used, one for each 32-bit wide "slice" of permissions. The UUID returned in manager_type_chain refers to the next ACL manager in the chain. If there are no more ACL managers for this ACL, uuid_nil is returned. manager_info Provides a name and helpstring for the given ACL manager. tokenize When FALSE, this variable indicates that the returned permission printstrings are unambiguous and therefore may be concatenated when printed without confusion. When TRUE, however, this property does not hold, and the strings need to be separated when printed or passed. total_num_printstrings An unsigned 32-bit integer containing the total number of permission printstrings supported by this ACL manager type. size_used An unsigned 32-bit integer containing the number of permission entries returned in the printstrings[] array. printstrings[] An array of permission printstrings of type sec_acl_printstring_t. Each entry of the array is a structure containing the following three components: printstring A character string of maximum length sec_acl_printstring_len describing the printable representation of a specified permission. helpstring A character string of maximum length sec_acl_printstring_help_len containing some text that can be used to describe the specified permission. permissions A sec_acl_permset_t permission set describing the permissions that are represented with the companion printstring. The array consists of one such entry for each permission supported by the ACL manager identified by manager_type. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_acl_get_printstring() routine returns an array of printable representations (called "printstrings") for each permission bit or combination of permission bits the specified ACL manager supports. The ACL manager type specified must be one of the types protecting the object indicated by h. In addition to returning the printstrings, this routine also returns instructions about how to print the strings. When the tokenize variable is set to FALSE, a printstring might be r or w, which could be concatenated in the display as rw without any confusion. However, when the tokenize variable is TRUE, it implies the printstrings might be of a form like read or write, which must be displayed separated by spaces or colons or something. In any list of permission printstrings, there may appear to be some redundancy. ACL managers often define aliases for common permission combinations. By convention, however, simple entries should appear at the beginning of the printstrings[] array, and combinations should appear at the end. FILES SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL The idl file from which dce/daclif.h was derived. ERRORS sec_acl_unknown_manager_type The manager type selected is not among those referenced by the input handle. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_acl_bind sec_acl_get_manager_types 4 sec_acl_lookup NAME sec_acl_lookup - Returns the ACL for an object SYNOPSIS #include void sec_acl_lookup( sec_acl_handle_t h, uuid_t *manager_type, sec_acl_type_t sec_acl_type, sec_acl_list_t *sec_acl_list, error_status_t *status); PARAMETERS Input h A handle referring to the target object. Use sec_acl_bind() to create this handle. manager_type A pointer to the UUID identifying the type of the ACL manager in question. There may be more than one type of ACL manager protecting the object whose ACL is bound to the input handle. Use this parameter to distinguish them. Use sec_acl_get_manager_types() to acquire a list of the manager types protecting a given object. sec_acl_type The ACL type. The sec_acl_type_t data type distinguishes the various types of ACLs an object can possess for a given manager type. The possible values are as follows: + sec_acl_type_object + sec_acl_type_default_object + sec_acl_type_default_container Output sec_acl_list A pointer to the sec_acl_list_t structure to receive the complete Access Control List. An ACL contains a list of ACL entries, the UUID of the default cell where authentication takes place (foreign entries in the ACL contain the name of their home cell), and the UUID of the ACL manager to interpret the list. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_acl_lookup() routine loads into memory a copy of an object's ACL corresponding to the specified manager type. The routine returns a pointer to the ACL. This routine is only used by ACL editors and browsers; an application would use sec_acl_test_access() or sec_acl_test_access_on_behalf() to process the contents of an ACL. Permissions Required The sec_acl_lookup() routine requires at least one permission of any kind on the object for which the ACL is to be returned. NOTES The memory containing the sec_acl_t structure for each ACL is dynamically allocated. Use the sec_acl_release() routine to return each ACL's memory block to the pool when an application is finished with the ACLs. FILES SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL The idl file from which dce/daclif.h was derived. ERRORS sec_acl_unknown_manager_type The manager type selected is not an available option. sec_acl_cant_allocate_memory The requested operation requires more memory than is avail- able. RELATED INFORMATION Functions: sec_intro sec_acl_bind sec_acl_test_access sec_acl_test_access_on_behalf 4 sec_acl_release NAME sec_acl_release - Releases ACL storage SYNOPSIS #include void sec_acl_release( sec_acl_handle_t h, sec_acl_t *sec_acl, error_status_t *status); PARAMETERS Input h A handle referring to the target object. Use sec_acl_bind() to create this handle. sec_acl A pointer to the complete ACL associated with the target object. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_acl_release() routine releases any local storage associated with the ACL object, returning it to the pool. This is strictly a local operation (since the storage in question is local), and has no effect on the remote object or its ACL. The ACL handle is in the argument list only for consistency with other sec_acl routines. FILES SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL The idl file from which dce/daclif.h was derived. ERRORS error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_acl_bind sec_acl_lookup 4 sec_acl_release_handle NAME sec_acl_release_handle - Removes an ACL handle SYNOPSIS #include void sec_acl_release_handle( sec_acl_handle_t *h, error_status_t *status); PARAMETERS Input h The handle to be removed. The handle is bound to the object to which the ACL belongs with the sec_acl_bind() routine. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_acl_release_handle() routine removes the specified handle. This is strictly a local operation, and has no effect on the remote object or its ACL. FILES SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL The idl file from which dce/daclif.h was derived. ERRORS error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_acl_bind 4 sec_acl_replace NAME sec_acl_replace - Replaces an ACL SYNOPSIS #include void sec_acl_replace( sec_acl_handle_t h, uuid_t *manager_type, sec_acl_type_t sec_acl_type, sec_acl_list_t *sec_acl_list, error_status_t *status); PARAMETERS Input h A handle referring to the target object. Use sec_acl_bind() to create this handle. manager_type A pointer to the UUID identifying the type of the ACL manager in question. There may be more than one type of ACL manager protecting the object whose ACL is bound to the input handle. Use this parameter to distinguish them. Use sec_acl_get_manager_types() to acquire a list of the manager types protecting a given object. sec_acl_type The ACL type. The sec_acl_type_t data type distinguishes the various types of ACLs an object can possess for a given manager type. The possible values are as follows: + sec_acl_type_object + sec_acl_type_default_object + sec_acl_type_default_container sec_acl_list The new ACL to use for the target object. This is represented by a pointer to the sec_acl_list_t structure containing the complete Access Control List. An ACL contains a list of ACL entries, the UUID of the default cell where authentication will take place (foreign entries in the ACL contain the name of their parent cell), and the UUID of the ACL manager to interpret the list. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_acl_replace() routine replaces the ACL indicated by the input handle with the information in the sec_acl_list parameter. ACLs are thought of as immutable, and in order to modify them, an editing application must read an entire ACL (using the sec_acl_lookup() routine), modify it as needed, and replace it using this routine. Permissions Required The sec_acl_replace() routine requires the c (control) permission on the object for which the ACL is to be replaced. FILES SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL The idl file from which dce/daclif.h was derived. ERRORS sec_acl_unknown_manager_type The manager type selected is not an available option. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_acl_bind sec_acl_lookup 4 sec_acl_test_access NAME sec_acl_test_access - Tests access to an object SYNOPSIS #include boolean32 sec_acl_test_access( sec_acl_handle_t h, uuid_t *manager_type, sec_acl_permset_t desired_permset, error_status_t *status); PARAMETERS Input h A handle referring to the target object. Use sec_acl_bind() to create this handle. manager_type A pointer to the UUID identifying the type of the ACL manager in question. There may be more than one type of ACL manager protecting the object whose ACL is bound to the input handle. Use this parameter to distinguish them. Use sec_acl_get_manager_types() to acquire a list of the manager types protecting a given object. desired_permset A permission set in sec_acl_permset_t form containing the desired privileges. This is a 32-bit set of permission flags supported by the manager type. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_acl_test_access() routine determines if the specified ACL contains entries granting privileges to the calling process matching those in desired_permset. An application generally only inquires after the minimum set of privileges needed to accomplish a specific task. Permissions Required The sec_acl_test_access() routine requires at least one permission of any kind on the object for which the privileges are to be tested. FILES SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL The idl file from which dce/daclif.h was derived. RETURN VALUES The routine returns TRUE if the calling application program is authorized to access the target object with the privileges in desired_permset. ERRORS sec_acl_unknown_manager_type The manager type selected is not an available option. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_acl_bind sec_acl_test_access_on_behalf 4 sec_acl_test_access_on_behalf NAME sec_acl_test_access_on_behalf - Tests access to an object on behalf of another process SYNOPSIS #include boolean32 sec_acl_test_access_on_behalf( sec_acl_handle_t h, uuid_t *manager_type, sec_id_pac_t *subject, sec_acl_permset_t desired_permset, error_status_t *status); PARAMETERS Input h A handle referring to the target object. Use sec_acl_bind() to create this handle. manager_type A pointer to the UUID identifying the type of the ACL manager in question. There may be more than one type of ACL manager protecting the object whose ACL is bound to the input handle. Use this parameter to distinguish them. Use sec_acl_get_manager_types() to acquire a list of the manager types protecting a given object. subject A Privilege Attribute Certificate (PAC) for the subject process. The PAC contains the name and UUID of the principal and cell of the subject process, as well as a list of any groups to which it belongs. The PAC also contains a flag (named authenticated). When set, it indicates that the certificate was obtained from an authenticated source. When not set, the certificate must not be trusted. (The field is FALSE when it was obtained from the rpc_auth layer and the protect level was set to rpc_c_protect_level_none. This indicates that no authentication protocol was actually used in the remote procedure call; the identity was simply transmitted from the caller to the callee. If an authentication protocol was used, then the flag is set to TRUE.) If a null PAC is passed, the subject is treated as an "anonymous user", matching only the any_other and unauthenticated entries (if they exist) on the ACL. A server uses rpc_binding_inq_auth_client() to acquire a certificate for the client process. desired_permset A permission set in sec_acl_permset_t form containing the desired privileges. This is a 32-bit set of permission flags supported by the manager type. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_acl_test_access_on_behalf() routine determines if the specified ACL contains entries that grant the privileges specified in desired_permset to the subject process. An application generally inquires about only the minimum set of privileges needed to accomplish a specific task. Permissions Required The sec_acl_test_access_on_behalf() routine requires at least one permission of any kind on the object for which the privileges are to be tested. Both the calling process and the identified subject must have permission on the object. FILES SYS$COMMON:[DCE$LIBRARY]DACLIF.IDL The idl file from which dce/daclif.h was derived. RETURN VALUES If the routine completes successfully (with a completion status of error_status_ok) it returns a value of + TRUE if the caller has any access (at least one permission of any kind), and the subject has the desired_permset privileges. + FALSE if both the caller and the subject have any access, but the subject does not have the desired_permset privileges. If the routine does not complete successfully, it returns a bad completion status code and a return value of FALSE. ERRORS sec_acl_unknown_manager_type The manager type selected is not an available option. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_acl_bind sec_acl_test_access rpc_binding_inq_auth_client 4 sec_attr_trig_query NAME sec_attr_trig_query - Reads attributes coded with an attribute trigger type of query SYNOPSIS #include void sec_attr_trig_query ( handle_t h, sec_attr_component_name_t cell_name, sec_attr_component_name_t component_name, sec_attr_trig_cursor_t *cursor, unsigned32 num_attr_keys, unsigned32 space_avail, sec_attr_t attr_keys[], unsigned32 *num_returned, sec_attr_t attrs[], sec_attr_trig_timeval_sec_t time_to_live[], unsigned32 *num_left, error_status_t *status); PARAMETERS Input h A handle referring to the trigger server to be accessed Use the trigger binding information specified in the attribute encoding to acquire a bound handle. cell_name A value of sec_attr_component_name_t that identifies the cell in which the object whose attribute is to be accessed resides. Supply a NULL cell_name to specify the local cell (/.:). component_name A value of sec_attr_component_name_t that identifies the name of the object whose attribute is to be accessed. If cell_name specifies a foreign cell, component_name is interpreted as a UUID in string format since the caller of this interface knows only the UUID, not the name, of the foreign principal. num_attr_keys An unsigned 32-bit integer that specifies the number of elements in the attr_keys[] array. This integer must be greater than 0. space_avail An unsigned 32-bit integer that specifies the size of the attr_keys[] array. attr_keys[] An array of values of type sec_attr_t. For each attribute instance, the sec_attr_t array contains an attr_id (a UUID of type uuid_t) to identify the attribute to be queried and an attr_value. attr_value can be used to pass in optional information required by the attribute trigger query. If no additional information is to be passed, set attr_value to sec_attr_enc_void. This is actually accomplished by setting the sec_attr_encoding_t data type to sec_attr_enc_void. The size of the attr_keys[] array is determined by num_attr_keys. Input/Output cursor A pointer to a cursor of type sec_attr_trig_cursor_t. As an input parameter, cursor can be initialized (by the sec_addr_trig_cursor_init routine) or uninitialized. As an output parameter, cursor is positioned past the attributes returned in this call. Output num_returned A pointer to an unsigned 32-bit integer that specifies the number of attribute instances returned in the attr_keys[] array. attrs[] An array of values of type sec_attr_t. The size of this array is determined by the space_avail parameter and the length by the num_returned parameter. time_to_live[], An array of values of type sec_attr_trig_timeval_sec_t. For each attribute in the attrs[] array, The time_to_live[] array specifies the time in seconds that the attribute can be safely cached. num_left A pointer to an unsigned 32-bit integer that supplies the number of attributes found but not returned because of space constraints in the attrs[] buffer. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_attr_trig_query() routine reads attributes coded with an attribute trigger type of query. The sec_attr_trig_query() routine is called by the DCE attribute lookup code for all schema entries that specify a query attribute trigger (sec_attr_trig_type_query specified with the sec_attr_trig_type_flags_t data type). The attribute query code passes the sec_attr_trig_query() input parameters to a user-written query attribute trigger server and receives the output parameters back from the server. Although generally this routine it is not called directly, this reference page is provided for users who are writing the attribute trigger servers that will receive sec_attr_trig_query() input and supply its output. Multi-valued attributes are returned as independent attribute instances sharing the same attribute UUID. A read of an attribute set returns all instances of members of the set; the attribute set instance is not returned. For objects in the local cell, set the cell_name parameter to null, and the component_name parameter to specify the object's name. For objects in a foreign cell, set the cell_name parameter to identify the name of the foreign cell, and the component_name parameter to the UUID in string format that identifies the object in the foreign cell. The cursor parameter specifies a cursor of type sec_attr_trig_cursor_t that establishes the point in the attribute list at which to start processing the query. Use the sec_attr_trig_cursor_init function to initialize a list cursor. If cursor is uninitialized, the server begins processing the query at the first attribute that satisfies the search criteria. Note that generally, sec_attr_trig_cursor_init function makes a remote call to the specified server. To initialize the cursor without making this remote call, set the sec_attr_trig_cursor_init function valid parameter to 0. The num_left parameter contains the number of attributes that were found but could not be returned because of space constraints of the attrs[] array. (Note that this number may be inaccurate if the target server allows updates between successive queries.) To obtain all of the remaining attributes, set the size of the attrs[] array so that it is large enough to hold the number of attributes listed in num_left. FILES SYS$COMMON:[DCE$LIBRARY]SEC_ATTR_TRIG.IDL The idl file from which sec_attr_trig.h was derived. ERRORS not_all_available unauthorized error_status_ok RELATED INFORMATION Functions: sec_intro sec_attr_trig_cursor_init sec_attr_trig_update 4 sec_attr_trig_update NAME sec_attr_trig_update - For attributes coded with an attribute trigger type of update, passes attribute updates to an update attribute trigger server for evaluation SYNOPSIS #include void sec_attr_trig_update ( handle_t h, sec_attr_component_name_t cell_name, sec_attr_component_name_t component_name, unsigned32 num_to_write, unsigned32 space_avail, sec_attr_t in_attrs[], unsigned32 *num_returned, sec_attr_t out_attrs[], unsigned32 *num_left, signed32 *failure_index, error_status_t *status); PARAMETERS Input h A handle referring to the trigger server to be accessed. Use the trigger binding information specified in the attribute encoding to acquire a bound handle. cell_name A value of sec_attr_component_name_t that identifies the cell in which the object whose attribute is to be accessed resides. Supply a NULL cell_name to specify the local cell (/.:). component_name A value of sec_attr_component_name_t that identifies the name of the object whose attribute is to be accessed. If cell_name specifies a foreign cell, component_name is interpreted as a UUID in string format since the caller of this interface knows only the UUID, not the name, of the foreign principal. num_to_write An unsigned 32-bit integer that specifies the number of elements in the in_attrs array. This integer must be greater than 0. space_avail An unsigned 32-bit integer that specifies the size of the out_attrs array. in_attrs[] An array of values of type sec_attr_t that specifies the attribute instances to be written. The size of in_attrs[] is determined by num_to_write. Output num_returned A pointer to an unsigned 32-bit integer that specifies the number of attribute instances returned in the out_attrs[] array. out_attrs[] An array of values of type sec_attr_t. These values, supplied by the update attribute trigger server, are in a form suitable for storage in the registry database. num_left A pointer to an unsigned 32-bit integer that supplies the number of attributes that were found but not returned because of space constraints in the out_attrs[] buffer. failure_index In the event of an error, failure_index is a pointer to the element in the in_attrs[] array that caused the update to fail. If the failure cannot be attributed to a specific attribute, the value of failure_index is -1. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_attr_trig_update() routine passes attributes coded with an attribute trigger type of update to a user-written update attribute trigger server for evaluation before the updates are made to the registry. Although generally this routine it is not called directly, this reference page is provided for users who are writing the attribute trigger servers that will receive sec_attr_trig_update() input and supply its output. The sec_attr_trig_update() routine is called by the DCE attribute update code for all schema entries that specify an update attribute trigger (sec_attr_trig_type_update specified with the sec_attr_trig_type_flags_t data type). The attribute update code passes the sec_attr_trig_update() input parameters to a user-written update attribute trigger server and receives the output parameters back from the server. The attribute trigger server is responsible for evaluating the semantics of the entry in order to reject or accept it, and the attribute trigger server may even make changes in the output it sends back to the update code to ensure the entry adheres to the semantics. The output received from the attribute trigger server is in a form to be stored in the registry. (Note that update attribute trigger servers do not store attribute values. Attribute values are stored in the registry database.) This is an atomic operation: if the update of any attribute in the array fails to pass the evaluation, all updates are aborted. The attribute causing the update to fail is identified in failure_index. If the failure cannot be attributed to a given attribute, failure_index contains -1. For objects in the local cell, set the cell_name parameter to null, and the component_name parameter to specify the object's name. For objects in a foreign cell, set the cell_name parameter the the name of the foreign cells, and the component_name parameter to specify the UUID in string format that identifies the object in the foreign cell. FILES SYS$COMMON:[DCE$LIBRARY]SEC_ATTR_TRIG.IDL The idl file from which dce/sec_attr_trig.h was derived. ERRORS database read only server unavailable invalid/unsupported attribute type invalid encoding type value not unique site read only unauthorized error_status_ok RELATED INFORMATION Functions: sec_intro sec_attr_trig_query 4 sec_cred_free_attr_cursor NAME sec_cred_free_attr_cursor - Free the local resources allocated to a sec_attr_cursor_t used by the sec_cred_get_extended_attrs() call SYNOPSIS #include void sec_cred_free_attr_cursor ( sec_cred_attr_cursor_t *cursor, error_status_t *status); PARAMETERS Input/Output cursor As input, a pointer to a sec_cred_attr_cursor_t whose resources are to be freed. As output a pointer to an initialized sec_cred_attr_cursor_t with allocated resources freed. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_cred_free_attr_cursor() routine frees the resources assoicated with a cursor of type sec_cred_attr_cursor_t used by the sec_cred_get_extended_attrs() call. ERRORS error_status_ok RELATED INFORMATION Functions: sec_intro sec_cred_get_extended_attrs sec_cred_initialize_attr_cursor 4 sec_cred_free_cursor NAME sec_cred_free_cursor - Release local resources allocated to a sec_cred_cursor_t used by the sec_cred_get_delegate() call SYNOPSIS #include void sec_cred_free_cursor ( sec_cred_cursor_t *cursor, error_status_t *status); PARAMETERS Input/Output cursor As input, a sec_cred_cursor_t whose resources are to be freed. As output, a sec_cred_cursor_t whose resources are freed. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_cred_free_cursor() routine releases local resources allocated to a sec_cred_cursor_t used by the sec_cred_get_delegate() call. ERRORS sec_login_s_no_memory error_status_ok RELATED INFORMATION Functions: sec_intro sec_cred_get_delegate sec_cred_initialize_cursor 4 sec_cred_free_pa_handle NAME sec_cred_free_pa_handle - Free the local resources allocated to a privilege attribute handle of type sec_cred_pa_handle_t used by the sec_cred_get_initiator() and sec_cred_get_delegate() calls SYNOPSIS #include void sec_cred_free_pa_handle ( sec_cred_pa_handle__t *pa_handle, error_status_t *status); PARAMETERS Input/Output pa_handle As input, a pointer to a sec_cred_pa_handle_t whose resources are to be freed. As output a pointer to a sec_cred_pa_handle_t with allocated resources freed. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_cred_free_pa_handle() routine frees the resources assoicated with a privilege attribute handle of type sec_cred_pa_handle_t used by the sec_cred_get_initiator() and sec_cred_get_delegate() calls. ERRORS error_status_ok RELATED INFORMATION Functions: sec_intro sec_cred_get_initiator sec_cred_get_delegate 4 sec_cred_get_authz_session_info NAME sec_cred_get_authz_session_info - Returns session-specific information that represents an authenticated client's credentials. SYNOPSIS #include void sec_cred_get_authz_session_info( rpc_authz_cred_handle_t callers_identity, uuid_t *session_id, sec_timeval_t *session_expiration, error_status_t *status ); PARAMETERS Input callers_identity A credential handle of type rpc_authz_cred_handle_t. This handle is supplied as output of the rpc_binding_inq_auth_caller() call. Output session_ID A pointer to a uuid_t that identifies the client's DCE authorization session. session_expiration A pointer to a sec_timeval_t that specifies the expiration time of the authenticated client's credentials. status A pointer to the completion status. On successful completion, status is assigned error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_cred_get_authz_session_info() routine retrieves session-specific information that represents the credentials of authenticated client specified by callers_identity. If the client is a member of a delegation chain, the information represents the credentials of all members of the chain. The information can aid application servers in the construction of identity-based caches. For example, it could be used as a key into a cache of previously allocated delegation contexts and thus avoid the overhead of allocating a new login context on every remote operation. It could also be used as a key into a table of previously computed authorization decisions. Before you execute this call, you must execute an rpc_binding_inq_auth_caller() call to obtain an rpc_authz_cred_handle_t for the callers_identity parameter. ERRORS sec_cred_s_authz_cannot_comply error_status_ok RELATED INFORMATION Functions: sec_intro rpc_binding_inq_auth_caller 4 sec_cred_get_client_princ_name NAME sec_cred_get_client_princ_name - Returns the principal name associated with a credential handle SYNOPSIS #include void sec_cred_get_client_princ_name( rpc_authz_cred_handle_t callers_identity, unsigned_char_p_t *client_princ_name, error_status_t *status); PARAMETERS Input callers_identity A handle of type rpc_authz_cred_handle_t to the credentials for which to return the principal name. This handle is supplied as output of the rpc_binding_inq_auth_caller() call. Output client_princ_name A pointer to the principal name of the server's rpc client. status A pointer to the completion status. On successful completion, status is assigned error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_cred_get_client_princ_name() routine extracts the principal name associated with the credentials identified by callers_pas. Before you execute sec_cred_get_client_princ_name(), you must execute an rpc_binding_inq_auth_caller() call to obtain an rpc_authz_cred_handle_t for the callers_identity parameter. ERRORS sec_cred_s_authz_cannot_comply error_status_ok RELATED INFORMATION Functions: sec_intro rpc_binding_inq_auth_caller 4 sec_cred_get_deleg_restrictions NAME sec_cred_get_deleg_restrictions - Returns delegate restrictions from a privilege attribute handle SYNOPSIS #include sec_id_restriction_set_t *sec_cred_get_deleg_restrictions( sec_cred_pa_handle_t callers_pas, error_status_t *status); PARAMETERS Input callers_pas A value of type sec_cred_pa_handle_t that provides a handle to a principal's privilege attributes. This handle is supplied as output of the sec_cred_get_initiator() call, the sec_cred_get_delegate() call and the sec_login_cred calls. Output status A pointer to the completion status. On successful completion, status is assigned error_status_ok. DESCRIPTION The sec_cred_get_deleg_restrictions () routine extracts delegate restrictions from the privilege attribute handle identified by callers_pas. The restrictions are returned in a sec_id_restriction_set_t. Before you execute sec_cred_get_pa_data(), you must execute a sec_cred_get_initiator() or sec_cred_get_delegate() call to obtain a sec_cred_pa_handle_t for the callers_pas parameter. ERRORS sec_cred_s_invalid_pa_handle error_status_ok RELATED INFORMATION Functions: sec_intro sec_cred_get_delegate sec_cred_get_initiator 4 sec_cred_get_delegate NAME sec_cred_get_delegate - Returns a handle to the privilege attributes of an intermediary in a delegation chain SYNOPSIS #include sec_cred_pa_handle_t sec_cred_get_delegate( rpc_authz_cred_handle_t callers_identity, sec_cred_cursor_t *cursor, error_status_t *status); PARAMETERS Input callers_identity A handle of type rpc_authz_cred_handle_t. This handle is supplied as output of the rpc_binding_inq_auth_caller() call. Input/Output cursor As input, a pointer to a cursor of type sec_cred_cursor_t that has been initialized by the sec_cred_initialize_cursor() call. As an output parameter, cursor is a pointer to a cursor of type sec_attr_srch_cursor_t that is positioned past the principal whose privilege attributes have been returned in this call. Output status A pointer to the completion status. On successful completion, status is assigned error_status_ok. DESCRIPTION The sec_cred_get_delegate() routine returns a handle to the the privilege attributes of an intermediary in a delegation chain that performed an authenticated RPC operation. This call is used by servers. Clients use the sec_login_cred_get_delegate() routine to return the privilege attribute handle of an intermediary in a delegation chain. The credential handle identified by callers_identity contains authenti- cation and authorization information for all delegates in the chain. This call returns a handle (sec_cred_pa_handle_t) to the privilege attributes of one of the delegates in the binding handle. The sec_cred_pa_handle_t returned by this call is used in other sec_cred_get... calls to obtain privilege attribute information for a single delegate. To obtain the privilege attributes of each delegate in the credential handle identified by callers_identity, execute this call until the message sec_cred_s_no_more_entries is returned. Before you execute sec_cred_get_delegate(), you must execute: + An rpc_binding_inq_auth_caller() call to obtain an rpc_authz_cred_handle_t for the callers_identity parameter. + A sec_cred_initialize_cursor() call to initialize a cursor of type sec_cred_cursor_t. Use the sec_cred_free_pa_handle() all to free the resources associated with the sec_cred_pa_handle_t. ERRORS sec_cred_s_invalid_auth_handle sec_cred_s_invalid_cursor sec_cred_s_no_more_entries error_status_ok RELATED INFORMATION Functions: sec_intro rpc_binding_inq_auth_caller sec_cred_initialize_cursor sec_cred_get_deleg_restrictions sec_cred_get_delegation_type sec_cred_get_extended_attrs sec_cred_get_opt_restrictions sec_cred_get_pa_date sec_cred_get_req_restrictions sec_cred_get_tgt_restrictions sec_cred_get_v1_pac sec_cred_free_pa_handle 4 sec_cred_get_delegation_type NAME sec_cred_get_delegation_type - Returns the delegation type from a privilege attribute handle SYNOPSIS #include sec_id_delegation_type_t *sec_cred_get_delegation_type( sec_cred_pa_handle_t callers_pas, error_status_t *status); PARAMETERS Input callers_pas A value of type sec_cred_pa_handle_t that provides a handle to a principal's privilege attributes. This handle is supplied as output of either the sec_cred_get_initiator() call or ec_cred_get_delegate() call. Output status A pointer to the completion status. On successful completion, status is assigned error_status_ok. DESCRIPTION The sec_cred_get_delegation_type () routine extracts the delegation type from the privilege attribute handle identified by callers_pas and returns it in a sec_id_delegation_type_t. Before you execute sec_cred_get_delegation_type(), you must execute a sec_cred_get_initiator() or sec_cred_get_delegate() call to obtain a sec_cred_pa_handle_t for the callers_pas parameter. ERRORS sec_cred_s_invalid_pa_handle error_status_ok RELATED INFORMATION Functions: sec_intro sec_cred_get_delegate sec_cred_get_initiator 4 sec_cred_get_extended_attrs NAME sec_cred_get_extended_attrs - Returns extended attributes from a privilege handle SYNOPSIS #include void sec_cred_get_extended_attrs( sec_cred_pa_handle_t callers_pas, sec_cred_attr_cursor_t *cursor sec_attr_t *attr error_status_t *status); PARAMETERS Input callers_pas A handle of type sec_cred_pa_handle_t to the caller's privilege attributes. This handle is supplied as output of either the sec_cred_get_initiator() call or sec_cred_get_delegate() call. Input/Output cursor A cursor of type sec_cred_attr_cursor_t that has been initialized by the sec_cred_initialize_attr_cursor() routine. As input cursor must be initialized. As output, cursor is positioned at the first attribute after the returned attribute. Output attr A pointer to a value of sec_attr_t that contains extended registry attributes. status A pointer to the completion status. On successful completion, status is assigned error_status_ok. DESCRIPTION The sec_cred_get_extended_attrs() routine extracts extended registry initialized from the privilege attribute handle identified by callers_pas. Before you execute call, you must execute: + A sec_cred_get_initiator() or sec_cred_get_delegate() call to obtain a sec_cred_pa_handle_t for the callers_pas parameter. + A sec_cred_initialize_attr_cursor() to initialize a sec_attr_t. To obtain all the extended registry attributes in the privilege attribute handle, repeat sec_cred_get_extended_attrs() calls until the status message no_more_entries_available is returned. ERRORS sec_cred_s_invalid_pa_handle sec_cred_s_invalid_cursor sec_cred_s_no_more_entries error_status_ok RELATED INFORMATION Functions: sec_intro sec_cred_initialize_attr_cursor sec_cred_get_initiator sec_cred_get_delegate 4 sec_cred_get_initiator NAME sec_cred_get_initiator - Returns the privilege attributes of the initiator of a delegation chain SYNOPSIS #include sec_cred_pa_handle_t sec_cred_get_initiator( rpc_authz_cred_handle_t callers_identity, error_status_t *status); PARAMETERS Input callers_identity A credential handle of type rpc_authz_cred_handle_t. This handle is supplied as output of the rpc_binding_inq_auth_caller() call. Output status A pointer to the completion status. On successful completion, status is assigned error_status_ok. DESCRIPTION The sec_cred_get_initiator() routine returns a handle to the the privilege attributes of the initiator of a delegation chain that performed an authenticated RPC operation. The credential handle identified by callers_identity contains authentication and authorization information for all delegates in the chain. This call returns a handle (sec_cred_pa_handle_t) to the privilege attributes of the client that initiated the delegation chain. The sec_cred_pa_handle_t returned by this call is used in other sec_cred_get... calls to obtain privilege attribute information for the initiator. Before you execute sec_cred_get_initiator(), you must execute an rpc_binding_inq_auth_caller() call to obtain an rpc_authz_cred_handle_t for the callers_identity parameter. ERRORS sec_cred_s_invalid_auth_handle error_status_ok RELATED INFORMATION Functions: sec_intro rpc_binding_inq_auth_caller sec_cred_get_deleg_restrictions sec_cred_get_delegation_type sec_cred_get_extended_attrs sec_cred_get_opt_restrictions sec_cred_get_pa_date sec_cred_get_req_restrictions sec_cred_get_tgt_restrictions sec_cred_get_v1_pac 4 sec_cred_get_opt_restrictions NAME sec_cred_get_opt_restrictions - Returns optional restrictions from a privilege handle SYNOPSIS #include sec_id_opt_req_t *sec_cred_get_opt_restrictions( sec_cred_pa_handle_t callers_pas, error_status_t *status); PARAMETERS Input callers_pas A handle of type sec_cred_pa_handle_t to a principal's privilege attributes. This handle is supplied as output of either the sec_cred_get_initiator() call or sec_cred_get_delegate() call. Output status A pointer to the completion status. On successful completion, status is assigned error_status_ok. DESCRIPTION The sec_cred_get_opt_restrictions () routine extracts optional restrictions from the privilege attribute handle identified by callers_pas and returns them in a sec_id_restriction_set_t. Before you execute sec_cred_get_pa_data(), you must execute a sec_cred_get_initiator() or sec_cred_get_delegate() call to obtain a sec_cred_pa_handle_t for the callers_pas parameter. ERRORS sec_cred_s_invalid_pa_handle error_status_ok RELATED INFORMATION Functions: sec_intro sec_cred_get_delegate sec_cred_get_initiator 4 sec_cred_get_pa_data NAME sec_cred_get_pa_data - Returns identity information from a privilege attribute handle SYNOPSIS #include sec_id_pa_t *sec_cred_get_pa_data( sec_cred_pa_handle_t callers_pas, error_status_t *status); PARAMETERS Input callers_pas A handle of type sec_cred_pa_handle_t to a principal's privilege attributes. This handle is supplied as output of either the sec_cred_get_initiator() call or sec_cred_get_delegate() call. Output status A pointer to the completion status. On successful completion, status is assigned error_status_ok. DESCRIPTION The sec_cred_get_pa_data() routine extracts identity information from the privilege attribute handle specified by callers_pas and returns it in a sec_id_pa_t. The identity information includes an identifier of the princpal's locall cell and the principal's local and foreign group sets. Before you execute sec_cred_get_pa_data(), you must execute a sec_cred_get_initiator() or sec_cred_get_delegate() call to obtain a sec_cred_pa_handle_t for the callers_pas parameter. ERRORS sec_cred_s_invalid_pa_handle error_status_ok RELATED INFORMATION Functions: sec_intro sec_cred_get_delegate sec_cred_get_initiator 4 sec_cred_get_req_restrictions NAME sec_cred_get_req_restrictions - Returns required restrictions from a privilege attribute handle SYNOPSIS #include sec_id_opt_req_t *sec_cred_get_req_restrictions ( sec_cred_pa_handle_t callers_pas, error_status_t *status); PARAMETERS Input callers_pas A handle of type sec_cred_pa_handle_t to a principal's privilege attributes. This handle is supplied as output of either the sec_cred_get_initiator() call or sec_cred_get_delegate() call. Output status A pointer to the completion status. On successful completion, status is assigned error_status_ok. DESCRIPTION The sec_cred_get_req_restrictions() routine extracts required restrictions from the privilege attribute handle identified by callers_pas and returns them in a sec_id_opt_req_t. Before you execute sec_cred_get_req_restrictions(), you must execute a sec_cred_get_initiator() or sec_cred_get_delegate() call to obtain a sec_cred_pa_handle_t for the callers_pas parameter. ERRORS sec_cred_s_invalid_pa_handle error_status_ok RELATED INFORMATION Functions: sec_intro sec_cred_get_delegate sec_cred_get_initiator 4 sec_cred_get_tgt_restrictions NAME sec_cred_get_tgt_restrictions - Returns target restrictions from a privilege attribute handle SYNOPSIS #include sec_id_restriction_set_t *sec_cred_get_tgt_restrictions( sec_cred_pa_handle_t callers_pas, error_status_t *status); PARAMETERS Input callers_pas A handle of type sec_cred_pa_handle_t to a principal's privilege attributes. This handle is supplied as output of either the sec_cred_get_initiator() call or sec_cred_get_delegate() call. Output status A pointer to the completion status. On successful completion, status is assigned error_status_ok. DESCRIPTION The sec_cred_get_tgt_restrictions() routine extracts target restrictions from the privilege attribute handle identified by callers_pas and returns them in a sec_id_restriction_set_t. Before you execute sec_cred_get_tgt_restrictions(), you must execute a sec_cred_get_initiator() or sec_cred_get_delegate() call to obtain a sec_cred_pa_handle_t for the callers_pas parameter. ERRORS sec_cred_s_invalid_pa_handle error_status_ok RELATED INFORMATION Functions: sec_intro sec_cred_get_delegate sec_cred_get_initiator 4 sec_cred_get_v1_pac NAME sec_cred_get_v1_pac - Returns pre-1.1 PAC from a privilege attribute handle SYNOPSIS #include sec_id_pac_t *sec_cred_get_v1_pac( sec_cred_pa_handle_t callers_pas, error_status_t *status); PARAMETERS Input callers_pas A handle of type sec_cred_pa_handle_t to the principal's privilege attributes. This handle is supplied as output of either the sec_cred_get_initiator() call or sec_cred_get_delegate() call. Output status A pointer to the completion status. On successful completion, status is assigned error_status_ok. DESCRIPTION The sec_cred_get_v1_pac() routine extracts the privilege attributes from a pre-1.1 PAC for the privilege attribute handle specified by callers_pas and returns them in a sec_id_pa_t. Before you execute sec_cred_get_v1_pac(), you must execute a sec_cred_get_initiator() or sec_cred_get_delegate() call to obtain a sec_cred_pa_handle_t for the callers_pas parameter. ERRORS sec_cred_s_invalid_pa_handle error_status_ok RELATED INFORMATION Functions: sec_intro sec_cred_get_delegate sec_cred_get_initiator 4 sec_cred_initialize_attr_cursor NAME sec_cred_initialize_attr_cursor - Initialize a sec_attr_cursor_t used by the sec_cred_get_extended_attrs() call SYNOPSIS #include void sec_cred_initialize_attr_cursor ( sec_cred_attr_cursor_t *cursor, error_status_t *status); PARAMETERS Input/Output cursor As input, a pointer to a sec_cred_attr_cursor_t to be initialized. As output a pointer to an initialized sec_cred_attr_cursor_t. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_cred_initialize_attr_cursor() routine allocates and initializes a cursor of type sec_cred_attr_cursor_t for use with the sec_cred_get_extended_attrs() call. Use the sec_cred_free_attr_cursor() call to free the resources allocated to cursor. ERRORS sec_login_s_no_memory error_status_ok RELATED INFORMATION Functions: sec_intro sec_cred_get_extended_attrs sec_cred_free_attr_cursor 4 sec_cred_initialize_cursor NAME sec_cred_initialize_cursor - Initialize a sec_cred_cursor_t used by the sec_cred_get_delegate() call SYNOPSIS #include void sec_cred_initialize_cursor ( sec_cred_cursor_t *cursor, error_status_t *status); PARAMETERS Input/Output cursor As input, a sec_cred_cursor_t to be initialized. As output, an initialized sec_cred_cursor_t. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_cred_initialize_cursor() routine initializes a cursor of type sec_cursor_t for use with the sec_cred_get_delegate() call. Use the sec_cred_free_cursor() call to free the resources allocated to cursor. ERRORS sec_login_s_no_memory error_status_ok RELATED INFORMATION Functions: sec_intro sec_cred_get_delegate sec_cred_free_cursor 4 sec_cred_is_authenticated NAME sec_cred_is_authenticated - Returns true if the supplied credentials are authenticated and false if they are not SYNOPSIS #include boolean32 sec_cred_is_authenticated( rpc_authz_cred_handle_t callers_identity, error_status_t *status); PARAMETERS Input callers_identity A handle of type rpc_authz_cred_handle_t to the credentials to check for authentication. This handle is supplied as output of the rpc_binding_inq_auth_caller() call. Output status A pointer to the completion status. On successful completion, status is assigned error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_cred_is_authenticated() routine returns true if the credentials identified by callers_identity are authenticated or false if they are not. Before you execute this call, you must execute an rpc_binding_inq_auth_caller() call to obtain an rpc_authz_cred_handle_t for the callers_identity parameter. FILES SYS$COMMON:[DCE$LIBRARY]SEC_CRED.IDL The idl file from which dce/sec_cred.h was derived. RETURN VALUES The routine returns true is the credentials are authenticated; false if they are not. ERRORS TBS RELATED INFORMATION Functions: sec_intro rpc_binding_inq_auth_caller 4 sec_id_gen_group NAME sec_id_gen_group - Generates a global name from cell and group UUIDs SYNOPSIS #include void sec_id_gen_group( sec_rgy_handle_t context, uuid_t *cell_idp, uuid_t *group_idp, sec_rgy_name_t global_name, sec_rgy_name_t cell_namep, sec_rgy_name_t group_namep, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. cell_idp A pointer to the UUID of the home cell of the group whose name is in question. group_idp A pointer to the UUID of the group whose name is in question. Output global_name The global (full) name of the group in sec_rgy_name_t form. cell_namep The name of the group's home cell in sec_rgy_name_t form. group_namep The local (with respect to the home cell) name of the group in sec_rgy_name_t form. status A pointer to the completion status. On successful completion, the function returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_id_gen_group() routine generates a global name from input cell and group UUIDs. For example, given a UUID specifying the cell /.../world/hp/brazil, and a UUID specifying a group resident in that cell named writers, the routine would return the global name of that group, in this case, /.../world/hp/brazil/writers. It also returns the simple names of the cell and group, translated from the UUIDs. The routine will not produce translations to any name for which a NULL pointer has been supplied. FILES SYS$COMMON:[DCE$LIBRARY]SECIDMAP.IDL The idl file from which dce/secidmap.h was derived. ERRORS sec_id_e_name_too_long The name is too long for current implementation. sec_id_e_bad_cell_uuid The cell UUID is not valid. sec_rgy_object_not_found The registry server could not find the specified group. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_id_gen_name sec_id_parse_group sec_id_parse_name 4 sec_id_gen_name NAME sec_id_gen_name - Generates a global name from cell and principal UUIDs SYNOPSIS #include void sec_id_gen_name( sec_rgy_handle_t context, uuid_t *cell_idp, uuid_t *princ_idp, sec_rgy_name_t global_name, sec_rgy_name_t cell_namep, sec_rgy_name_t princ_namep, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. cell_idp A pointer to the UUID of the home cell of the principal whose name is in question. princ_idp A pointer to the UUID of the principal whose name is in question. Output global_name The global (full) name of the principal in sec_rgy_name_t form. cell_namep The name of the principal's home cell in sec_rgy_name_t form. princ_namep The local (with respect to the home cell) name of the principal in sec_rgy_name_t form. status A pointer to the completion status. On successful completion, the function returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_id_gen_name() routine generates a global name from input cell and principal UUIDs. For example, given a UUID specifying the cell /.../world/hp/brazil, and a UUID specifying a principal resident in that cell named writers/tom, the routine would return the global name of that principal, in this case, /.../world/hp/brazil/writers/tom. It also returns the simple names of the cell and principal, translated from the UUIDs. The routine will not produce translations to any name for which a NULL pointer has been supplied. Permissions Required The sec_id_gen_name() routine requires at least one permission of any kind on the account associated with the input cell and principal UUIDs. FILES SYS$COMMON:[DCE$LIBRARY]SECIDMAP.IDL The idl file from which dce/secidmap.h was derived. ERRORS sec_id_e_name_too_long The name is too long for current implementation. sec_id_e_bad_cell_uuid The cell UUID is not valid. sec_rgy_object_not_found The registry server could not find the specified principal. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_id_gen_group sec_id_parse_group sec_id_parse_name 4 sec_id_parse_group NAME sec_id_parse_group - Translates a global name into group and cell names and UUIDs SYNOPSIS #include void sec_id_parse_group( sec_rgy_handle_t context, sec_rgy_name_t global_name, sec_rgy_name_t cell_namep, uuid_t *cell_idp, sec_rgy_name_t group_namep, uuid_t *group_idp, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. global_name The global (full) name of the group in sec_rgy_name_t form. Output cell_namep The output name of the group's home cell in sec_rgy_name_t form. cell_idp A pointer to the UUID of the home cell of the group whose name is in question. group_namep The local (with respect to the home cell) name of the group in sec_rgy_name_t form. group_idp A pointer to the UUID of the group whose name is in question. status A pointer to the completion status. On successful completion, the function returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_id_parse_group() routine translates a global group name into a cell name and a cell-relative group name. It also returns the UUIDs associated with the group and its home cell. The routine will not produce translations to any name for which a NULL pointer has been supplied. FILES SYS$COMMON:[DCE$LIBRARY]SECIDMAP.IDL The idl file from which dce/secidmap.h was derived. ERRORS sec_id_e_name_too_long The name is too long for current implementation. sec_id_e_bad_cell_uuid The cell UUID is not valid. sec_rgy_object_not_found The registry server could not find the specified group. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_id_gen_group sec_id_gen_name sec_id_parse_group sec_id_parse_name 4 sec_id_parse_name NAME sec_id_parse_name - Translates a global name into principal and cell names and UUIDs SYNOPSIS #include void sec_id_parse_name( sec_rgy_handle_t context, sec_rgy_name_t global_name, sec_rgy_name_t cell_namep, uuid_t *cell_idp, sec_rgy_name_t princ_namep, uuid_t *princ_idp, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. global_name The global (full) name of the principal in sec_rgy_name_t form. Output cell_namep The output name of the principal's home cell in sec_rgy_name_t form. cell_idp A pointer to the UUID of the home cell of the principal whose name is in question. princ_namep The local (with respect to the home cell) name of the principal in sec_rgy_name_t form. princ_idp A pointer to the UUID of the principal whose name is in question. status A pointer to the completion status. On successful completion, the function returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_id_parse_name() routine translates a global principal name into a cell name and a cell-relative principal name. It also returns the UUIDs associated with the principal and its home cell. The routine will not produce translations to any name for which a NULL pointer has been supplied. Permissions Required Only if princ_idp is requested as output does the sec_id_parse_name() routine require a permission. In this case, the routine requires at least one permission of any kind on the account whose global principal name is to be translated. FILES SYS$COMMON:[DCE$LIBRARY]SECIDMAP.IDL The idl file from which dce/secidmap.h was derived. ERRORS sec_id_e_name_too_long The name is too long for current implementation. sec_id_e_bad_cell_uuid The cell UUID is not valid. sec_rgy_object_not_found The registry server could not find the specified principal. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_id_gen_name 4 sec_key_mgmt_change_key NAME sec_key_mgmt_change_key - Changes a principal's key SYNOPSIS #include void sec_key_mgmt_change_key( sec_key_mgmt_authn_service authn_service, void *arg, idl_char *principal_name, unsigned32 key_vno, void *keydata, sec_timeval_period_t *garbage_collect_time, error_status_t *status); PARAMETERS Input authn_service Identifies the authentication protocol using this key. The possible authentication protocols are as follows: rpc_c_authn_dce_secret DCE shared-secret key authentication. rpc_c_authn_dce_public DCE public key authentication (reserved for future use). arg This parameter can specify either the local key file or an argument to the get_key_fn key acquisition routine of the rpc_server_register_auth_info routine. A value of NULL specifies that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;) should be used. A key file name specifies that file should be used as the key file. You must prepend the file's absolute filename with FILE: and the file must have been created with the rgy_edit ktadd command or the sec_key_mgmt_set_key function. Any other value specifies an argument for the get_key_fn key acquisition routine. See the rpc_server_register_auth_info reference page for more information. principal_name A pointer to a character string indicating the name of the principal whose key is to be changed. key_vno The version number of the new key. If 0 (zero) is specified, the routine will select the next appropriate key version number. keydata A pointer to a structure of type sec_passwd_rec_t. Output garbage_collect_time The number of seconds that must elapse before all currently valid tickets (which are encoded with the current or previous keys) expire. At that time, all obsolete keys may be "garbage collected", since no valid tickets encoded with those keys will remain outstanding on the network. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_key_mgmt_change_key() routine performs all activities necessary to update a principal's key to the specified value. This includes updating any local storage for the principal's key and also performing any remote operations needed to keep the authentication protocol (or network registry) current. Old keys for the principal are garbage collected if appropriate. FILES The idl file from which dce/keymgmt.h was derived. ERRORS Any error condition will leave the key state unchanged. sec_key_mgmt_e_key_unavailable The old key is not present and therefore cannot be used to set a client side authentication context. sec_key_mgmt_e_authn_invalid The authentication protocol is not valid. sec_key_mgmt_e_auth_unavailable The authentication protocol is not available to update the network database or to obtain the necessary network credentials. sec_key_mgmt_e_unauthorized The caller is not authorized to perform the operation. sec_key_mgmt_e_key_unsupported The key type is not supported. sec_key_mgmt_e_key_version_ex A key with this version number already exists. sec_rgy_server_unavailable The DCE Registry Server is unavailable. sec_rgy_object_not_found No principal was found with the given name. sec_login_s_no_memory A memory allocation error occurred. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_key_mgmt_generate_key sec_key_mgmt_set_key 4 sec_key_mgmt_delete_key NAME sec_key_mgmt_delete_key - Deletes a key from the local storage SYNOPSIS #include void sec_key_mgmt_delete_key( sec_key_mgmt_authn_service authn_service, void *arg, idl_char *principal_name, unsigned32 key_vno, error_status_t *status); PARAMETERS Input authn_service Identifies the authentication protocol using this key. The possible authentication protocols are as follows: rpc_c_authn_dce_secret DCE shared-secret key authentication. rpc_c_authn_dce_public DCE public key authentication (reserved for future use). arg This parameter can specify either the local key file or an argument to the get_key_fn key acquisition routine of the rpc_server_register_auth_info routine. A value of NULL specifies that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;) should be used. A key file name specifies that file should be used as the key file. You must prepend the file's absolute filename with FILE: and the file must have been created with the rgy_edit ktadd command or the sec_key_mgmt_set_key function. Any other value specifies an argument for the get_key_fn key acquisition routine. See the rpc_server_register_auth_info() reference page for more information. principal_name A pointer to a character string indicating the name of the principal whose key is to be deleted. key_vno The version number of the desired key. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_key_mgmt_delete_key() routine deletes the specified key from the local key store. If an administrator ever discovers or suspects that the security of a server's key has been compromised, the administrator should delete the key immediately with sec_key_mgmt_delete_key(). This routine removes the key from the local key storage, which invalidates all extant tickets encoded with the key. If the compromised key is the current one, the principal should change the key with sec_key_mgmt_change_key() before deleting it. It is not an error for a process to delete the current key (as long as it is done after the network context has been established), but it may seriously inconvenience legitimate clients of a service. This routine deletes all key types that have the specified key version number. A key type identifies the data encryption algorithm being used (for example, DES). This routine differs from sec_key_mgmt_delete_key_type() in that sec_key_mgmt_delete_key_type() deletes only the specified key version of the specified key type from the local key store. FILES SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL The idl file from which dce/keymgmt.h was derived. ERRORS Any error condition will leave the key state unchanged. sec_key_mgmt_e_key_unavailable The requested key is not present. sec_key_mgmt_e_authn_invalid The authentication protocol is not valid. sec_key_mgmt_e_unauthorized The caller is not authorized to perform the operation. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_key_mgmt_delete_key_type sec_key_mgmt_garbage_collect 4 sec_key_mgmt_delete_key_type NAME sec_key_mgmt_delete_key_type - Deletes a key version of a key type from the local key storage SYNOPSIS #include void sec_key_mgmt_delete_key_type( sec_key_mgmt_authn_service authn_service, void *arg, idl_char *principal_name, void *keytype, unsigned32 key_vno, error_status_t *status); PARAMETERS Input authn_service Identifies the authentication protocol using this key. The possible authentication protocols are as follows: rpc_c_authn_dce_secret DCE shared-secret key authentication. rpc_c_authn_dce_public DCE public key authentication (reserved for future use). arg This parameter can specify either the local key file or an argument to the get_key_fn key acquisition routine of the rpc_server_register_auth_info routine. A value of NULL specifies that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;) should be used. A key file name specifies that file should be used as the key file. You must prepend the file's absolute filename with FILE: and the file must have been created with the rgy_edit ktadd command or the sec_key_mgmt_set_key routine. Any other value specifies an argument for the get_key_fn key acquisition routine. See the rpc_server_register_auth_info() reference page for more information. principal_name A pointer to a character string indicating the name of the principal whose key type is to be deleted. keytype A pointer to a value of type sec_passwd_type_t. The value identifies the data encryption algorithm that is being used (for example, DES). key_vno The version number of the desired key. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_key_mgmt_delete_key_type() routine deletes the specified key version of the specified key type from the local key store. It differs from sec_key_mgmt_delete_key() in that sec_key_mgmt_delete_key() deletes all key types that have the same key version number. This routine removes the key from the local key storage, which invalidates all extant tickets encoded with the key. If the key in question is the current one, the principal should change the key with sec_key_mgmt_change_key() before deleting it. It is not an error for a process to delete the current key (as long as it is done after the network context has been established), but it may seriously inconvenience legitimate clients of a service. FILES SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL The idl file from which dce/keymgmt.h was derived. ERRORS Any error condition will leave the key state unchanged. sec_key_mgmt_e_key_unavailable The requested key is not present. sec_key_mgmt_e_authn_invalid The authentication protocol is not valid. sec_key_mgmt_e_unauthorized The caller is not authorized to perform the operation. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_key_mgmt_delete_key sec_key_mgmt_garbage_collect 4 sec_key_mgmt_free_key NAME sec_key_mgmt_free_key - Frees the memory used by a key value SYNOPSIS #include void sec_key_mgmt_free_key( void *keydata, error_status_t *status); PARAMETERS Input keydata A pointer to a structure of type sec_passwd_rec_t. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. DESCRIPTION The sec_key_mgmt_free_key() routine releases any storage allocated for the indicated key data by sec_key_mgmt_get_key(). The storage for the key data returned by sec_key_mgmt_get_key() is dynamically allocated. FILES SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL The idl file from which dce/keymgmt.h was derived. ERRORS error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_key_mgmt_get_key 4 sec_key_mgmt_garbage_collect NAME sec_key_mgmt_garbage_collect - Deletes obsolete keys SYNOPSIS #include void sec_key_mgmt_garbage_collect( sec_key_mgmt_authn_service authn_service, void *arg, idl_char *principal_name, error_status_t *status); PARAMETERS Input authn_service Identifies the authentication protocol using this key. The possible authentication protocols are as follows: rpc_c_authn_dce_secret DCE shared-secret key authentication. rpc_c_authn_dce_public DCE public key authentication (reserved for future use). arg This parameter can specify either the local key file or an argument to the get_key_fn key acquisition routine of the rpc_server_register_auth_info routine. A value of NULL specifies that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;) should be used. A key file name specifies that file should be used as the key file. You must prepend the file's absolute filename with FILE: and the file must have been created with the rgy_edit ktadd command or the sec_key_mgmt_set_key routine. Any other value specifies an argument for the get_key_fn key acquisition routine. See the rpc_server_register_auth_info() reference page for more information. principal_name A pointer to a character string indicating the name of the principal whose key information is to be garbage collected. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_key_mgmt_garbage_collect() routine discards any obsolete key information for this principal. An obsolete key is one that can only decode invalid tickets. As an example, consider a key that was in use on Monday, and was only used to encode tickets whose maximum lifetime was 1 day. If that key was changed at 8:00 a.m. Tuesday morning, then it would become obsolete by 8:00 a.m. Wednesday morning, at which time there could be no valid tickets outstanding. FILES SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL The idl file from which dce/keymgmt.h was derived. ERRORS sec_key_mgmt_e_authn_invalid The authentication protocol is not valid. sec_key_mgmt_e_unauthorized The caller is not authorized to perform the operation. Requested key not present. sec_rgy_server_unavailable The DCE Registry Server is unavailable. sec_rgy_object_not_found No principal was found with the given name. sec_login_s_no_memory A memory allocation error occurred. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_key_mgmt_delete_key 4 sec_key_mgmt_gen_rand_key NAME sec_key_mgmt_gen_rand_key - Generates a new random key of a specified key type SYNOPSIS #include void sec_key_mgmt_gen_rand_key( sec_key_mgmt_authn_service authn_service, void *arg, idl_char *principal_name, void *keytype, unsigned32 key_vno, void **keydata, error_status_t *status); PARAMETERS Input authn_service Identifies the authentication protocol using this key. The possible authentication protocols are as follows: rpc_c_authn_dce_secret DCE shared-secret key authentication. rpc_c_authn_dce_public DCE public key authentication (reserved for future use). arg This parameter can specify either the local key file or an argument to the get_key_fn key acquisition routine of the rpc_server_register_auth_info routine. A value of NULL specifies that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;) should be used. A key file name specifies that file should be used as the key file. You must prepend the file's absolute filename with FILE: and the file must have been created with the rgy_edit ktadd command or the sec_key_mgmt_set_key routine. Any other value specifies an argument for the get_key_fn key acquisition routine. See the rpc_server_register_auth_info() reference page for more information. principal_name A pointer to a character string indicating the name of the principal for whom the key is to be generated. keytype A pointer to a value of type sec_passwd_type_t. The value identifies the data encryption algorithm to be used for the key (for example, DES). key_vno The version number of the new key. Output keydata A pointer to a value of sec_passwd_rec_t. The storage for keydata is allocated dynamically, so the returned pointer actually indicates a pointer to the key value. The storage for this data may be freed with the sec_key_mgmt_free_key() function. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_key_mgmt_gen_rand_key() routine generates a new random key for a specified principal and of a specified key type. The generated key can be used with the sec_key_mgmt_change_key() and sec_key_mgmt_set_key() routines. Note that to initialize the random keyseed, the process must first make an authenticated call such as sec_rgy_site_open(). FILES SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL The idl file from which dce/keymgmt.h was derived. ERRORS sec_key_mgmt_e_not_implemented The specified keytype is not supported. sec_s_no_key_seed No random key seed has been set. sec_s_no_memory Unable to allocate memory. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_key_mgmt_change_key sec_key_mgmt_generate_key sec_key_mgmt_set_key 4 sec_key_mgmt_get_key NAME sec_key_mgmt_get_key - Retrieves a key from local storage SYNOPSIS #include void sec_key_mgmt_get_key( sec_key_mgmt_authn_service authn_service, void *arg, idl_char *principal_name, unsigned32 key_vno, void **keydata, error_status_t *status); PARAMETERS Input authn_service Identifies the authentication protocol using this key. The possible authentication protocols are as follows: rpc_c_authn_dce_secret DCE shared-secret key authentication. rpc_c_authn_dce_public DCE public key authentication (reserved for future use). arg This parameter can specify either the local key file or an argument to the get_key_fn key acquisition routine of the rpc_server_register_auth_info routine. A value of NULL specifies that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;) should be used. A key file name specifies that file should be used as the key file. You must prepend the file's absolute filename with FILE: and the file must have been created with the rgy_edit ktadd command or the sec_key_mgmt_set_key routine. Any other value specifies an argument for the get_key_fn key acquisition routine. See the rpc_server_register_auth_info() reference page for more information. principal_name A pointer to a character string indicating the name of the principal to whom the key belongs. key_vno The version number of the desired key. To return the latest version of the key, set this parameter to sec_c_key_version_none. Output keydata A pointer to a value of type sec_passwd_rec_t. The storage for keydata is allocated dynamically, so the returned pointer actually indicates a pointer to the key value. The storage for this data may be freed with the sec_key_mgmt_free_key() routine. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_key_mgmt_get_key() routine extracts the specified key from the local key store. FILES SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL The idl file from which dce/keymgmt.h was derived. ERRORS sec_key_mgmt_e_key_unavailable The requested key is not present. sec_key_mgmt_e_authn_invalid The authentication protocol is not valid. sec_key_mgmt_e_unauthorized The caller is not authorized to perform the operation. sec_s_no_memory Unable to allocate memory. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro 4 sec_key_mgmt_get_next_key NAME sec_key_mgmt_get_next_key - Retrieves successive keys from the local key storage SYNOPSIS #include void sec_key_mgmt_get_next_key( void *cursor, idl_char **principal_name, unsigned32 *key_vno, void **keydata, error_status_t *status); PARAMETERS Input cursor A pointer to the current cursor position in the local key storage. The cursor position is set via the routine sec_key_mgmt_initialize_cursor(). Output principal_name A pointer to a character string indicating the name of the principal associated with the extracted key. Free the storage for the principal name with the free() function. key_vno The version number of the extracted key. keydata A pointer to a value of type sec_passwd_rec_t. The storage for keydata is allocated dynamically, so the returned pointer actually indicates a pointer to the key value. The storage for this data may be freed with the sec_key_mgmt_free_key() function. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_key_mgmt_get_next_key() routine extracts the key pointed to by the cursor in the local key store and updates the cursor to point to the next key. By repeatedly calling this routine you can scan all the keys in the local store. FILES SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL The idl file from which dce/keymgmt.h was derived. ERRORS sec_key_mgmt_e_key_unavailable The requested key is not present. sec_key_mgmt_e_unauthorized The caller is not authorized to perform the operation. sec_s_no_memory Unable to allocate memory. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_key_mgmt_get_key sec_key_mgmt_initialize_cursor 4 sec_key_mgmt_get_next_kvno NAME sec_key_mgmt_get_next_kvno - Retrieves the next eligible key version number for a key SYNOPSIS #include void sec_key_mgmt_get_next_kvno( sec_key_mgmt_authn_service authn_service, void *arg, idl_char *principal_name, void *keytype, unsigned32 *key_vno, unsigned32 *next_key_vno, error_status_t *status); PARAMETERS Input authn_service Identifies the authentication protocol using this key. The possible authentication protocols are as follows: rpc_c_authn_dce_secret DCE shared-secret key authentication. rpc_c_authn_dce_public DCE public key authentication (reserved for future use). arg This parameter can specify either the local key file or an argument to the get_key_fn key acquisition routine of the rpc_server_register_auth_info routine. A value of NULL specifies that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;) should be used. A key file name specifies that file should be used as the key file. You must prepend the file's absolute filename with FILE: and the file must have been created with the rgy_edit ktadd command or the sec_key_mgmt_set_key routine. Any other value specifies an argument for the get_key_fn key acquisition routine. See the rpc_server_register_auth_info() reference page for more information. principal_name A pointer to a character string indicating the name of the principal associated with the key. keytype A pointer to a value of type sec_passwd_type_t. The value identifies the data encryption algorithm (for example, DES) being used for the key. Output key_vno The current version number of the key. Specify NULL if you do not need this value to be returned. next_key_vno The next eligible version number for the key. Specify NULL if you do not need this value to be returned. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_key_mgmt_get_next_kvno() routine returns the current and next eligible version numbers for a key from the registry server (not from the local key table). The key is identified via its associated authentication protocol, principal name, and key type. The arg value associated with the key is also specified. FILES SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL The idl file from which dce/keymgmt.h was derived. ERRORS sec_key_mgmt_e_key_unavailable The requested key is not present. sec_key_mgmt_e_authn_invalid The authentication protocol is not valid. sec_key_mgmt_e_unauthorized The caller is not authorized to perform the operation. sec_rgy_server_unavailable The DCE Registry Server is unavailable. sec_rgy_object_not_found No principal was found with the given name. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro 4 sec_key_mgmt_initialize_cursor NAME sec_key_mgmt_initialize_cursor - Repositions the cursor in the local key store SYNOPSIS #include void sec_key_mgmt_initialize_cursor( sec_key_mgmt_authn_service authn_service, void *arg, idl_char *principal_name, void *keytype, void **cursor, error_status_t *status); PARAMETERS Input authn_service Identifies the authentication protocol using this key. The possible authentication protocols are as follows: rpc_c_authn_dce_secret DCE shared-secret key authentication. rpc_c_authn_dce_public DCE public key authentication (reserved for future use). arg This parameter can specify either the local key file or an argument to the get_key_fn key acquisition routine of the rpc_server_register_auth_info routine. A value of NULL specifies that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;) should be used. A key file name specifies that file should be used as the key file. You must prepend the file's absolute filename with FILE: and the file must have been created with the rgy_edit ktadd command or the sec_key_mgmt_set_key routine. Any other value specifies an argument for the get_key_fn key acquisition routine. See the rpc_server_register_auth_info() reference page for more information. principal_name A pointer to a character string indicating the name of the principal whose key is to be accessed. To access all keys in the local key store, supply NULL for this parameter. keytype A pointer to the data encryption algorithm (for example, DES) being used for the key. Output cursor The returned cursor value. The storage for the cursor information is allocated dynamically, so the returned pointer actually indicates a pointer to the cursor value. The storage for this data may be freed with the sec_key_mgmt_release_cursor() routine. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_key_mgmt_initialize_cursor() routine resets the cursor in the local key store. Use this routine to reposition the cursor before performing a scan of the local store via sec_key_mgmt_get_next_key(). The returned cursor value is supplied as input to sec_key_mgmt_get_next_key(). FILES SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL The idl file from which dce/keymgmt.h was derived. ERRORS sec_s_no_memory Unable to allocate memory. sec_key_mgmt_e_authn_invalid The authentication protocol is not valid. sec_key_mgmt_e_unauthorized The caller is not authorized to perform the operation. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_key_mgmt_get_next_key sec_key_mgmt_release_cursor 4 sec_key_mgmt_manage_key NAME sec_key_mgmt_manage_key - Automatically changes a principal's key before it expires SYNOPSIS #include void sec_key_mgmt_manage_key( sec_key_mgmt_authn_service authn_service, void *arg, idl_char *principal_name, error_status_t *status); PARAMETERS Input authn_service Identifies the authentication protocol using this key. The possible authentication protocols are as follows: rpc_c_authn_dce_secret DCE shared-secret key authentication. rpc_c_authn_dce_public DCE public key authentication (reserved for future use). arg This parameter can specify either the local key file or an argument to the get_key_fn key acquisition routine of the rpc_server_register_auth_info routine. A value of NULL specifies that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;) should be used. A key file name specifies that file should be used as the key file. You must prepend the file's absolute filename with FILE: and the file must have been created with the rgy_edit ktadd command or the sec_key_mgmt_set_key routine. Any other value specifies an argument for the get_key_fn key acquisition routine. See the rpc_server_register_auth_info() reference page for more information. principal_name A pointer to a character string indicating the name of the principal whose key is to be managed. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_key_mgmt_manage_key() routine changes the specified principal's key on a regular basis, as determined by the local cell's policy. It will run indefinitely, never returning during normal operation, and therefore should be invoked only from a thread that has been devoted to managing keys. This routine queries the DCE Registry to determine the password expiration policy that applies to the named principal. It then idles until a short time before the current key is due to expire and then uses the sec_key_mgmt_gen_rand_key() to produce a new random key, updating both the local key store and the DCE Registry. This routine also invokes sec_key_mgmt_garbage_collect() as needed. FILES SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL The idl file from which dce/keymgmt.h was derived. ERRORS sec_key_mgmt_e_key_unavailable The old key is not present and therefore cannot be used to set a client side authentication context. sec_key_mgmt_e_key_unsupported The key type is not supported. sec_key_mgmt_e_authn_invalid The authentication protocol is not valid. sec_key_mgmt_e_unauthorized The caller is not authorized to perform the operation. sec_rgy_server_unavailable The DCE Registry Server is unavailable. sec_rgy_object_not_found No principal was found with the given name. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_key_mgmt_gen_rand_key sec_key_mgmt_garbage_collect 4 sec_key_mgmt_release_cursor NAME sec_key_mgmt_release_cursor - Releases the memory used by an initialized cursor value SYNOPSIS #include void sec_key_mgmt_release_cursor( void **cursor, error_status_t *status); PARAMETERS Input cursor A pointer to the cursor value for which the storage is to be released. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. DESCRIPTION The sec_key_mgmt_release_cursor() routine releases any storage allocated for the indicated cursor value by sec_key_mgmt_initialize_cursor(). The storage for the cursor value returned by sec_key_mgmt_initialize_cursor() is dynamically allocated. FILES SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL The idl file from which dce/keymgmt.h was derived. ERRORS sec_key_mgmt_e_unauthorized The caller is not authorized to perform the operation. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_key_mgmt_initialize_cursor 4 sec_key_mgmt_set_key NAME sec_key_mgmt_set_key - Inserts a key value into the local storage SYNOPSIS #include void sec_key_mgmt_set_key( sec_key_mgmt_authn_service authn_service, void *arg, idl_char *principal_name, unsigned32 key_vno, void *keydata, error_status_t *status); PARAMETERS Input authn_service Identifies the authentication protocol using this key. The possible authentication protocols are as follows: rpc_c_authn_dce_secret DCE shared-secret key authentication. rpc_c_authn_dce_public DCE public key authentication (reserved for future use). arg This parameter can specify either the local key file or an argument to the get_key_fn key acquisition routine of the rpc_server_register_auth_info routine. A value of NULL specifies that the default key file (DCE$LOCAL:[KRB]V5SRVTAB.;) should be used. A key file name specifies that file should be used as the key file. The file name must begin with FILE:. If the file name does not begin with FILE:, the code will add it. Any other value specifies an argument for the get_key_fn key acquisition routine. See the rpc_server_register_auth_info() reference page for more information. principal_name A pointer to a character string indicating the name of the principal associated with the key to be set. key_vno The version number of the key to be set. keydata A pointer to the key value to be set. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_key_mgmt_set_key() routine performs all local activities necessary to update a principal's key to the specified value. This routine will not update the authentication protocol's value for the principal's key. In some circumstances, a server may only wish to change its key in the local key storage, and not in the DCE Registry. For example, a database system may have several replicas of a master database, managed by servers running on independent machines. Since these servers together represent only one service, they should all share the same key. This way, a user with a ticket to use the database can choose whichever server is least busy. To change the database key, the master server would signal all the replica (slave) servers to change the current key in their local key storage. They would use the sec_key_mgmt_set_key() routine, which does not communicate with the DCE Registry. Once all the slaves have complied, the master server can then change the Registry key and its own local storage. FILES SYS$COMMON:[DCE$LIBRARY]KEYMGMT.IDL The idl file from which dce/keymgmt.h was derived. ERRORS sec_key_mgmt_e_key_unavailable The old key is not present and therefore cannot be used to set a client side authentication context. sec_key_mgmt_e_authn_invalid The authentication protocol is not valid. sec_key_mgmt_e_unauthorized The caller is not authorized to perform the operation. sec_key_mgmt_e_key_unsupported The key type is not supported. sec_key_mgmt_e_key_version_ex A key with this version number already exists. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_key_mgmt_change_key sec_key_mgmt_gen_rand_key 4 sec_login_become_delegate NAME sec_login_become_delegate - Causes an intermediate server to become a delegate in traced delegation chain SYNOPSIS #include sec_login_handle_t sec_login_become_delegate( rpc_authz_cred_handle_t callers_identity, sec_login_handle_t my_login_context, sec_id_delegation_type_t delegation_type_permitted, sec_id_restriction_set_t *delegate_restrictions, sec_id_restriction_set_t *target_restrictions, sec_id_opt_req_t *optional_restrictions, sec_id_opt_req_t *required_restrictions, sec_id_compatibility_mode_t compatibility_mode, error_status_t *status); PARAMETERS Input callers_identity A handle of type rpc_authz_cred_handle_t to the authenticated identity of the previous delegate in the delegation chain. The handle is supplied by the rpc_binding_inq_auth_caller() call. my_login_context A value of sec_login_handle_t that provides an opaque handle to the identity of the client that is becoming the intermediate delegate. The sec_login_handle_t that specifies the client's identity is supplied as output of the following calls: + sec_login_get_current_context() if the client inherited the identity of the current context + The sec_login_setup_identity() and the sec_login_validate_identity() pair that together establish an authenticated identity if a new identity was established Note that this identity specified by sec_login_handle_t must be a simple login context; it cannot be a compound identity created by a previous sec_login_become_delegate() call. delegation_type_permitted A value of sec_id_delegation_type_t that specifies the type of delegation to be enabled. The types available are: sec_id_deleg_type_none No delegation. sec_id_deleg_type_traced Traced delegation. sec_id_deleg_type_impersonation Simple (impersonation) delegation. Note that the initiating client sets the type of delegation. If it is set as traced, all delegates must also specify traced delegation; they cannot specify simple delegation. The same is true if the initiating client sets the delegation type as simple; all subsequent delegates must also specify simple delegation. The intermediate delegates can, however, specify no delegation to indicate that the delegation chain can proceed no further. delegate_restrictions A pointer to a sec_id_restriction_set_t that supplies a list of servers that can act as delegates for the intermediate client identified by my_login_context. These servers are added to delegates permitted by the delegate_restrictions parameter of the sec_login_become_initiator call. target_restrictions A pointer to a sec_id_restriction_set_t that supplies a list of servers that can act as targets for the intermediate client identified by my_login_context. These servers are added to targets specified by the target_restrictions parameter of the sec_login_become_initiator call. optional_restrictions A pointer to a sec_id_opt_req_t that supplies a list of application-defined optional restrictions that apply to the intermediate client identified by my_login_context. These restrictions are added to the restrictions identified by the optional_restrictions parameter of the sec_login_become_initiator call. required_restrictions A pointer to a sec_id_opt_req_t that supplies a list of application-defined required restrictions that apply to the intermediate client identified by my_login_context. These restrictions are added to the restrictions identified required_restrictions parameter of the sec_login_become_initiator call. compatibility_mode A value of sec_id_compatibility_mode_t that specifies the compatibility mode to be used when the intermediate client operates on pre-1.1 servers. The modes available are: sec_id_compat_mode_none Compatibility mode is off. sec_id_compat_mode_initiator Compatibility mode is on. The pre-1.1 PAC data is extracted from the EPAC of the initiating client. sec_id_compat_mode_caller Compatibility mode is on. The pre-1.1 PAC data extracted from the EPAC of the last client in the delegation chain. Output status A pointer to the completion status. On successful completion, status is assigned error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_login_become_delegate() is used by intermediate servers to become a delegate for the client identified by callers_identity. The routine returns a new login context (of type sec_login_handle_t) that carries delegation information. This information includes the delegation type, delegate and target restrictions, and any application-defined optional and required restrictions. The new login context created by this call can then used to to set up authenticated rpc with an intermediate or target server using the rpc_binding_set_auth_info() call. Any delegate, target, required, or optional restrictions specified in this call are added to the restrictions specified by the initiating client and any intermediate clients. The sec_login_become_delegate() call is run only if the initiating client enabled traced delegation by setting the delegation_type_permitted parameter in the sec_login_become_initiator call to sec_id_deleg_type_traced. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. ERRORS sec_login_s_invalid_context sec_login_s_compound_delegate sec_login_s_invalid_deleg_type err_sec_login_invalid_delegate_restriction err_sec_login_invalid_target_restriction err_sec_login_invalid_opt_restriction err_sec_login_invalid_req_restriction sec_login_s_invalid_compat_mode sec_login_s_deleg_not_enabled error_status_ok RELATED INFORMATION Functions: intro sec_login_become_initiator sec_login_become_impersonator rpc_binding_inq_auth_caller sec_login_get_current_context sec_login_setup_identity sec_login_validate_identity 4 sec_login_become_impersonator NAME sec_login_become_impersonator - Causes an intermediate server to become a delegate in a simple delegation chain SYNOPSIS #include sec_login_handle_t sec_login_become_impersonator( rpc_authz_cred_handle_t callers_identity, sec_id_delegation_type_t delegation_type_permitted, sec_id_restriction_set_t *delegate_restrictions, sec_id_restriction_set_t *target_restrictions, sec_id_opt_req_t *optional_restrictions, sec_id_opt_req_t *required_restrictions, error_status_t *status); PARAMETERS Input callers_identity A handle of type rpc_authz_cred_handle_t to the authenticated identity of the previous delegate in the delegation chain. The handle is supplied by the rpc_binding_inq_auth_caller() call. delegation_type_permitted A value of sec_id_delegation_type_t that specifies the type of delegation to be enabled. The types available are: sec_id_deleg_type_none No delegation. sec_id_deleg_type_traced Traced delegation. sec_id_deleg_type_impersonation Simple (impersonation) delegation. The initiating client sets the type of delegation. If it is set as traced, all delegates must also specify traced delegation; they cannot specify simple delegation. The same is true if the initiating client sets the delegation type as simple; all subsequent delegates must also specify simple delegation. The intermediate delegates can, however, specify no delegation to indicate that the delegation chain can proceed no further. delegate_restrictions A pointer to a sec_id_restriction_set_t that supplies a list of servers that can act as delegates for the client becoming the delegate. These servers are added to the delegates permitted by the delegate_restrictions parameter of the sec_login_become_initiator call. target_restrictions A pointer to a sec_id_restriction_set_t that supplies a list of servers that can act as targets for the client becoming the delegate. These servers are added to targets specified by the target_restrictions parameter of the sec_login_become_initiator call. optional_restrictions A pointer to a sec_id_opt_req_t that supplies a list of application-defined optional restrictions that apply to the client becoming the delegate. These restrictions are added to the restrictions identified by the optional_restrictions parameter of the sec_login_become_initiator call. required_restrictions A pointer to a sec_id_opt_req_t that supplies a list of application-defined required restrictions that apply to the client becoming the delegate. These restrictions are added to the restrictions identified required_restrictions parameter of the sec_login_become_initiator call. Output status A pointer to the completion status. On successful completion, status is assigned error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_login_become_impersonator() is used by intermediate servers to become a delegate for the client identified by callers_identity. The routine returns a new login context (of type sec_login_handle_t) that carries delegation information. This information includes the delegation type, delegate, and target restrictions, and any application-defined optional and required restrictions. The new login context created by this call can then used to to set up authenticated rpc with an intermediate or target server using the rpc_binding_set_auth_info() call. The effective optional and required restrictions are the union of the optional and required restrictions specified in this call and specified by the initiating client and any intermediate clients. The effective target and delegate restrictions are the intersection of the target and delegate restrictions specified in this call and specified by the initiating client and any intermediate clients. The sec_login_become_impersonator call is call is run only if the initiating client enabled simple delegation by setting the delegation_type_permitted parameter in the sec_login_become_initiator call to sec_id_deleg_type_simple. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. ERRORS sec_login_s_invalid_deleg_type err_sec_login_invalid_delegate_restriction err_sec_login_invalid_target_restriction err_sec_login_invalid_opt_restriction err_sec_login_invalid_req_restriction sec_login_s_invalid_compat_mode sec_login_s_deleg_not_enabled error_status_ok RELATED INFORMATION Functions: sec_intro sec_login_become_initiator rpc_binding_inq_auth_caller 4 sec_login_become_initiator NAME sec_login_become_initiator - Constructs a new login context that enables delegation for the calling client SYNOPSIS #include sec_login_handle_t sec_login_become_initiator( sec_login_handle_t my_login_context, sec_id_delegation_type_t delegation_type_permitted, sec_id_restriction_set_t *delegate_restrictions, sec_id_restriction_set_t *target_restrictions, sec_id_opt_req_t *optional_restrictions, sec_id_opt_req_t *required_restrictions, sec_id_compatibility_mode_t compatibility_mode, error_status_t *status); PARAMETERS Input my_login_context A value of sec_login_handle_t that provides an opaque handle to the identity of the client that is enabling delegation. The sec_login_handle_t that specifies the client's identity is supplied as output of the following calls: + sec_login_get_current_context() if the client inherited the identity of the current context + The sec_login_setup_identity() and the sec_login_validate_identity() pair that together establish an authentiated identity if a new identity was established delegation_type_permitted A value of sec_id_delegation_type_t that specifies the type of delegation to be enabled. The types available are: sec_id_deleg_type_none No delegation. sec_id_deleg_type_traced Traced delegation. sec_id_deleg_type_impersonation Simple (impersonation) delegation. Note each subsequent intermediate delegate of the delegation chain started by the initiating client must set the delegation type to traced if the initiating client set it to traced or to simple if the initiating client set it to simple. Intermediate delegates, however, can set the delegation type to no delegation to indicate that the delegation chain can proceed no further. delegate_restrictions A pointer to a sec_id_restriction_set_t that supplies a list of servers that can act as delegates for the client initiating delegation. target_restrictions A pointer to a sec_id_restriction_set_t that supplies a list of servers that can act as targets for the client initiating delegation. optional_restrictions A pointer to a sec_id_opt_req_t that supplies a list of application-defined optional restrictions that apply to the client initiating delegation. required_restrictions A pointer to a sec_id_opt_req_t that supplies a list of application-defined required restrictions that apply to the client initiating delegation. compatibility_mode A value of sec_id_compatibility_mode_t that specifies the compatibility mode to be used when the initiating client interacts with pre-1.1 servers. The modes available are: sec_id_compat_mode_none Compatibility mode is off. sec_id_compat_mode_initiator Compatibility mode is on. The pre-1.1 PAC data is extracted from the EPAC of the initiating client. sec_id_compat_mode_caller Compatibility mode is on. The pre-1.1 PAC data extracted from the EPAC of the last client in the delegation chain. Output status A pointer to the completion status. On successful completion, status is assigned error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_login_become_initiator() enables delegation for the calling client by constructing a new login context (in a sec_login_handle_t) that carries delegation information. This information includes the delegation type, delegate, and target restrictions, and any application-defined optional and required restrictions. The new login context is then used to to set up authenticated rpc with an intermediate server using the rpc_binding_set_auth_info() call. The intermediary can continue the delegation chain by calling sec_login_become_delegate (if the delegation type is sec_id_deleg_type_traced) or sec_login_become_impersonator (if the delegation type is sec_id_deleg_type_impersonation). FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. ERRORS sec_login_s_invalid_context sec_login_s_invalid_deleg_type err_sec_login_invalid_delegate_restriction err_sec_login_invalid_target_restriction err_sec_login_invalid_opt_restriction err_sec_login_invalid_req_restriction sec_login_s_invalid_compat_mode error_status_ok RELATED INFORMATION Functions: sec_intro sec_login_become_delegate sec_login_become_impersonator sec_login_get_current_context sec_login_setup_identity sec_login_validate_identity 4 sec_login_certify_identity NAME sec_login_certify_identity - Certifies the network authentication service SYNOPSIS #include boolean32 sec_login_certify_identity( sec_login_handle_t login_context, error_status_t *status); PARAMETERS Input login_context An opaque handle to login context data. The login context contains, among other data, the account principal name and UUID, account restrictions, records of group membership, and the process home directory. (See sec_intro for more details about the login context.) Output status A pointer to the completion status. On successful completion, status is assigned error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_login_certify_identity() routine certifies that the Security Server used to set up and validate a login context is legitimate. A legitimate server is one that knows the host machine's secret key. On some systems, this may be a privileged operation. Information may be retrieved via sec_login_get_pwent(), sec_login_get_groups(), and sec_login_get_expiration() from an uncertified login context, but such information cannot be trusted. All system login programs that use the sec_login interface must call sec_login_certify_identity() to certify the Security Server. If they do not, they open the local file system to attacks by imposter Security servers returning suspect local process credentials (UUID and group IDs). This operation updates the local registry with the login context credentials if the certification check succeeds. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. RETURN VALUES The routine returns a boolean32 value that is TRUE if the certification was successful, and FALSE otherwise. ERRORS sec_login_s_config The DCE configuration (dce_config) information is not available. sec_login_s_context_invalid The input context is invalid. sec_login_s_default_use It is an error to try to certify the default context. error_status_ok The call was successful. EXAMPLES Applications wishing to perform a straightforward login could use the sec_login package as follows: if (sec_login_setup_identity(user_name, sec_login_no_flags, &login_context, &st)) { ... get password from user... if (sec_login_validate_identity(login_context, password, &reset_passwd, &auth_src, &st)) { if (!sec_login_certify_identity(login_context, &st)) exit(error_weird_auth_svc); sec_login_set_context(login_context, &st); if (auth_src != sec_login_auth_src_network) printf("no network credentials"); if (reset_passwd) { ... get new password from user, reset registry record ... }; sec_login_get_pwent(login_context, &pw_entry, &st); if (pw_entry.pw_expire < todays_date) { sec_login_purge_context(&login_context, &st); exit(0) } ... any other application specific login valid actions ... } } else { sec_login_purge_context(&login_context, &st); ... application specific login failure actions ... } } RELATED INFORMATION Functions: sec_intro, sec_login_get_pwent sec_login_get_groups sec_login_get_expiration 4 sec_login_cred_get_delegate NAME sec_login_cred_get_delegate - Returns a handle to the privilege attributes of an intermediary in a delegation chain Used by clients. SYNOPSIS #include sec_cred_pa_handle_t sec_login_cred_get_delegate( sec_login_handle_t login_context, sec_cred_cursor_t *cursor, error_status_t *status); PARAMETERS Input login_context A value of sec_login_handle_t that provides an opaque handle to a login context for which delegation has been enabled. The sec_login_handle_t that specifies the identity is supplied as output of the sec_login_become_delegate() call. Input/Output cursor As input, a pointer to a cursor of type sec_cred_cursor_t that has been initialized by the sec_login_cred_init_cursor() call. As an output parameter, cursor is a pointer to a cursor of type sec_cred_cursor_t that is positioned past the principal whose privilege attributes have been returned in this call. Output status A pointer to the completion status. On successful completion, status is assigned error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_login_cred_get_delegate() routine returns a handle of type sec_login_handle_t to the the privilege attributes of an intermediary in a delegation chain that performed an authenticated RPC operation. This call is used by clients. Servers use the sec_cred_get_delegate() routine to return the privilege attribute handle of an intermediary in a delegation chain. The login context identified by login_context contains all members in the delegation chain. This call returns a handle (sec_cred_pa_handle_t) to the privilege attributes of one of the delegates in the login context. The sec_cred_pa_handle_t returned by this call is used in other sec_cred_get... calls to obtain privilege attribute information for a single delegate. To obtain the privilege attributes of each delegate in the credential handle identified by callers_identity, execute this call until the message sec_cred_s_no_more_entries is returned. Before you execute sec_login_cred_get_delegate(), you must execute a sec_login_cred_init_cursor() call to initialize a cursor of type sec_cred_cursor_t. Use the sec_cred_free_pa_handle() sec_cred_free_cursor() calls to free the resources allocated to the sec_cred_pa_handle_t and cursor. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. ERRORS sec_cred_s_invalid_cursor sec_cred_s_no_more_entries error_status_ok EXAMPLES RELATED INFORMATION Functions: sec_intro sec_login_cred_init_cursor sec_cred_get_pa_date sec_cred_get_extended_attrs sec_cred_get_v1_pac sec_cred_get_tgt_restrictions sec_cred_get_deleg_restrictions sec_cred_get_opt_restrictions sec_cred_get_req_restrictions sec_cred_get_delegation_type 4 sec_login_cred_get_initiator NAME sec_login_cred_get_initiator - Returns information about the delegation initiator in a specified login context SYNOPSIS #include sec_cred_pa_handle_t sec_login_cred_get_initiator( sec_login_handle_t login_context, error_status_t *status); PARAMETERS Input login_context A value of sec_login_handle_t that provides an opaque handle to a login context for which delegation has been enabled. Output status A pointer to the completion status. On successful completion, status is assigned error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_login_cred_get_initiator() routine returns a handle of type sec_cred_pa_handle_t to the privilege attributes of the delegation initiator. The login context identified by login_context contains all members in the delegation chain. This call returns a handle (sec_cred_pa_handle_t) to the privilege attributes of the initiator. The sec_cred_pa_handle_t returned by this call is used in other sec_cred_get... calls to obtain privilege attribute information for the initiator single delegate. Use the sec_cred_free_pa_handle() call to free the resources allocated to the sec_cred_pa_handle_t handle. FILES SYS$LIBRARY:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. ERRORS sec_login_s_invalid_context error_status_ok RELATED INFORMATION Functions: sec_intro sec_cred_get_pa_date sec_cred_get_extended_attrs sec_cred_get_v1_pac sec_cred_get_tgt_restrictions sec_cred_get_deleg_restrictions sec_cred_get_opt_restrictions sec_cred_get_req_restrictions sec_cred_get_delegation_type 4 sec_login_cred_init_cursor NAME sec_login_cred_init_cursor - Initialize a sec_cred_cursor_t SYNOPSIS #include void sec_login_cred_init_cursor ( sec_cred_cursor_t *cursor, error_status_t *status); PARAMETERS Input/Output cursor As input, a pointer to a sec_cred_cursor_t to be initialized. As output, a pointer to an initialized sec_cred_cursor_t. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_login_cred_init_cursor() routine allocates and initializes a cursor of type sec_cursor_t for use with the sec_login_cred_get_delegate() call. Use the sec_cred_free_cursor() call to free the resources allocated to cursor. ERRORS sec_cred_s_invalid_cursor sec_login_s_no_memory error_status_ok RELATED INFORMATION Functions: sec_intro sec_login_cred_get_delegate 4 sec_login_disable_delegation NAME sec_login_disable_delegation - Disables delegation for a specified login context SYNOPSIS #include sec_logon_handle_t *sec_login_disable_delegation( sec_login_handle_t login_context, error_status_t *status); PARAMETERS Input login_context An opaque handle to login context for which delegation has been enabled. Output status A pointer to the completion status. On successful completion, status is assigned error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_login_disable_delegation() routine disables delegation for a specified login context. It returns a new login context of type sec_login_handle_t without any delegation information, thus preventing any further delegation. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. ERRORS sec_login_s_invalid_context error_status_ok EXAMPLES RELATED INFORMATION Functions: sec_intro sec_login_become_initiator sec_login_become_delegate sec_login_become_impersonator 4 sec_login_export_context NAME sec_login_export_context - Creates an exportable login context SYNOPSIS #include void sec_login_export_context( sec_login_handle_t login_context, unsigned32 buf_len, idl_byte buf[], unsigned32 *len_used, unsigned32 *len_needed, error_status_t *status); PARAMETERS Input login_context An opaque handle to login context data. The login context contains, among other data, the account principal name and UUID, account restrictions, records of group membership, and the process home directory. (See sec_intro for more details about the login context.) buf_len An unsigned 32-bit integer containing the allocated length (in bytes) of the buffer that is to contain the login context. Output buf[] An idl_byte array that contains the exportable login context upon return. len_used A pointer to an unsigned 32-bit integer indicating the number of bytes needed for the entire login context, up to buf_len. len_needed If the allocated length of the buffer is too short, an error is issued (sec_login_s_no_memory), and on return this pointer indicates the number of bytes necessary to contain the login context. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_login_export_context() routine obtains an exportable version of the login context information. This information may be passed to another process running on the same machine. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. ERRORS sec_login_s_no_memory Not enough space was allocated for the buf[] array. The len_needed parameter will point to the needed length. sec_login_s_handle_invalid The login context handle is invalid. sec_login_s_context_invalid The login context specified by the input handle is invalid. RELATED INFORMATION Functions: sec_intro sec_login_import_context 4 sec_login_free_net_info NAME sec_login_free_net_info - Frees storage allocated for a principal's network information SYNOPSIS #include void sec_login_free_net_info( sec_login_net_info_t *net_info); PARAMETERS Input/Output net_info A pointer to the sec_login_net_info_t structure to be freed. DESCRIPTION The sec_login_free_net_info() routine frees any memory allocated for a principal's network information. Network information is returned by a previous successful call to sec_login_inquire_net_info(). CAUTIONS This routine does not return any completion codes. Make sure that you supply a valid sec_login_net_info_t address. The routine simply frees a range of storage beginning at the supplied address, without regard to the actual contents of the storage. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. RELATED INFORMATION Functions: sec_intro sec_login_inquire_net_info 4 sec_login_get_current_context NAME sec_login_get_current_context - Returns a handle to the current login context SYNOPSIS #include void sec_login_get_current_context( sec_login_handle_t *login_context, error_status_t *status); PARAMETERS Output login_context A pointer to an opaque handle to login context data. The login context contains, among other data, the account principal name and UUID, account restrictions, records of group membership, and the process home directory. (See sec_intro for more details about the login context.) status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_login_get_current_context() routine retrieves a handle to the login context for the currently established network identity. The context returned is created from locally cached data so subsequent data extraction operations may return some NULL values. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. ERRORS sec_login_s_no_current_context There was no current context to retrieve. (See sec_login_setup_identity for information about how to set up, validate, and implement a login context.) error_status_ok The call was successful. EXAMPLES The following example illustrates use of the sec_login_get_current_context() routine as part of a process to change the groupset: sec_login_get_current_context(&login_context, &st); sec_login_get_groups(login_context, &num_groups, &groups, &st); ...the group IDs have to be converted from the returned UNIX numbers into UUIDs (use sec_rgy_pgo_unix_num_to_id)... for (i=0; i < num_groups; i++) { ... query whether the user wants to discard any of the current group memberships. Copy new groupset to the new_groups array ... } if ( !sec_login_newgroups(sec_login_no_flags, num_new_groups, new_groups, &login_context, &st)) { if (st == sec_login_s_groupset_invalid) printf("New groupset invalid0); ... application specific error handling ... } RELATED INFORMATION Functions: sec_intro sec_login_setup_identity 4 sec_login_get_expiration NAME sec_login_get_expiration - Returns the TGT lifetime for an authenticated identity SYNOPSIS #include void sec_login_get_expiration( sec_login_handle_t login_context, signed32 *identity_expiration, error_status_t *status); PARAMETERS Input login_context An opaque handle to login context data. The login context contains, among other data, the account principal name and UUID, account restrictions, records of group membership, and the process home directory. (See sec_intro for more details about the login context.) Output identity_expiration The lifetime of the Ticket-Granting Ticket (TGT) belonging to the authenticated identity identified by login_context. It can be used in the same ways as a UNIX time_t. status A pointer to the completion status. On successful completion, the routine returns one of the following status codes: + error_status_ok to indicate that the login context has been validated and certified. + sec_login_s_not_certified to indicate that the login context has been validated, but not certified. Although this code indicates successful completion, it warns you that the context is not validated. If the call does not complete successfully, it returns an error. DESCRIPTION The sec_login_get_expiration() routine extracts the lifetime for the TGT belonging to the authenticated identity contained in the login context. The liftime value is filled in if available; otherwise, it is set to 0 (zero). This routine allows an application to tell an interactive user how long the user's network login (and authenticated identity) will last before having to be refreshed. The routine works only on previously certified contexts. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. ERRORS sec_login_s_context_invalid The login context itself is invalid. sec_login_s_default_use There was illegal use of the default login handle. sec_login_s_not_certified The login context has not been certified. sec_login_s_no_current_context The calling process has no context of its own. error_status_ok The call was successful. EXAMPLES Since the authenticated network identity for a process has a finite lifetime, there is a risk it will expire during some long network operation, preventing the operation from completing. To avoid this situation, an application might, before initiating a long operation, use the sec_login package to check the expiration time of its identity and refresh it if there is not enough time remaining to complete the operation. After refreshing the identity, the process must validate it again with sec_login_validate_identity(). sec_login_get_expiration(login_context, &expire_time, &st); if (expire_time < (current_time + operation_duration)) { if (!sec_login_refresh_identity(login_context, &st)) { if (st == sec_login_s_refresh_ident_bad) { ... identity has changed ... } else { ... login context cannot be renewed ... exit(error_context_not_renewable); } if (sec_login_validate_identity(login_context, password, &reset_passwd, &auth_src, &st)) { ... identity validated ... } else { ... validation failed ... exit(error_validation_failure); } } } operation(); RELATED INFORMATION Functions: sec_intro sec_login_get_current_context 4 sec_login_get_groups NAME sec_login_get_groups - Returns the groupset from a login context SYNOPSIS #include void sec_login_get_groups( sec_login_handle_t login_context, unsigned32 *num_groups, signed32 **group_set, error_status_t *status); PARAMETERS Input login_context An opaque handle to login context data. The login context contains, among other data, the account principal name and UUID, account restrictions, records of group membership, and the process home directory. (See sec_intro for more details about the login context.) Output num_groups An unsigned 32-bit integer indicating the total number of groups returned in the group_set array. group_set The list of groups to which the user belongs. status A pointer to the completion status. On successful completion, the routine returns one of the following status codes: + error_status_ok to indicate that the login context has been validated and certified. + sec_login_s_not_certified to indicate that the login context has been validated, but not certified. Although this code indicates successful completion, it warns you that the context is not validated. If the call does not complete successfully, it returns an error. DESCRIPTION The sec_login_get_groups() routine returns the groups contained in the supplied login context. Part of a network identity is a list of the various groups to which the principal belongs. The groups are used to determine a user's access to various objects and services. This routine extracts from the login context a list of the groups for which the user has established network privileges. The routine works only on previously validated contexts. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. ERRORS sec_login_s_context_invalid The login context itself is not valid. sec_login_s_info_not_avail The login context has no UNIX information. sec_login_s_default_use Illegal use of the default login handle occurred. sec_login_s_not_certified The login context has not been certified. sec_login_s_not_certified The login context is not certified. sec_rgy_object_not_found The registry server could not find the specified login context data. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. EXAMPLES The following example illustrates use of the sec_login_get_groups() routine as part of a process to change the groupset: sec_login_get_current_context(&login_context, &st); sec_login_get_groups(login_context, &num_groups, &groups, &st); ...the group IDs have to be converted from the returned UNIX numbers into UUIDs (use sec_rgy_pgo_unix_num_to_id)... for (i=0; i < num_groups; i++) { ... query whether the user wants to discard any of the current group memberships. Copy new groupset to the new_groups array ... } if ( !sec_login_newgroups(sec_login_no_flags, num_new_groups, new_groups, &login_context, &st)) { if (st == sec_login_s_groupset_invalid) printf("New groupset invalid0); ... application specific error handling ... } RELATED INFORMATION Functions: sec_intro sec_rgy_acct_get_projlist 4 sec_login_get_pwent NAME sec_login_get_pwent - Returns a passwd-style entry for a login context SYNOPSIS #include void sec_login_get_pwent( sec_login_handle_t login_context, sec_login_passwd_t *pwent, error_status_t *status); PARAMETERS Input login_context An opaque handle to login context data. The login context contains, among other data, the account principal name and UUID, account restrictions, records of group membership, and the process home directory. (See sec_intro for more details about the login context.) Output pwent A pointer to a pointer to the returned passwd-style structure. The particular structure depends on the underlying system. For example, on a system with a passwd structure like that supported by 4.4BSD and OSF/1, the structure (found in /usr/include/pwd.h) is: struct passwd { char *pw_name; /* user name */ char *pw_passwd; /* encrypted password */ int pw_uid; /* user uid */ int pw_gid; /* user gid */ time_t pw_change; /* password change time */ char *pw_class; /* user access class */ char *pw_gecos; /* miscellaneous account info */ char *pw_dir; /* home directory */ char *pw_shell; /* default shell */ time_t pw_expire; /* account expiration */ }; status A pointer to the completion status. On successful completion, the routine returns one of the following status codes: + error_status_ok to indicate that the login context has been validated and certified. + sec_login_s_not_certified to indicate that the login context has been validated, but not certified. Although this code indicates successful completion, it warns you that the context is not validated. If the call does not complete successfully, it returns an error. DESCRIPTION The sec_login_get_pwent() routine creates a passwd-style structure for the current network login context. This is generally useful for establishing the local operating system context. Applications that require all of the data normally extracted via getpwnam() should extract that data from the login context with this call. This routine works only on explicitly created (not inherited or imported) contexts. CAUTIONS The returned sec_login_passwd_t structure points to data stored in the structure indicated by the login_context pointer and must be treated as read-only data. Writing to these data objects may cause unexpected failures. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. EXAMPLES The following example illustrates use of the sec_login_get_pwent() routine: #include struct passwd *pwd; sec_login_get_pwent( login_context, &(sec_login_passwd_t*)pwd,&status ); printf ("%s",pwd->pw_name); ERRORS sec_login_s_context_invalid The login context itself is invalid. sec_login_s_not_certified The login context has not been certified. sec_login_s_default_use Illegal use of the default login handle occurred. sec_login_s_info_not_avail The login context has no UNIX information. sec_rgy_object_not_found The registry server could not find the specified login context data. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro 4 sec_login_import_context NAME sec_login_import_context - Imports a login context SYNOPSIS #include void sec_login_import_context( unsigned32 buf_len, idl_byte buf[], sec_login_handle_t *login_context, error_status_t *status); PARAMETERS Input buf_len The allocated length (in bytes) of the buffer containing the login context. buf[] An idl_byte array containing the importable login context. Output login_context An opaque handle to login context data. The login context contains, among other data, the account principal name and UUID, account restrictions, records of group membership, and the process home directory. (See sec_intro for more details about the login context.) status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_login_import_context() routine imports a context obtained via a call to sec_login_export_context() performed on the same machine. To import a login context, users must have the appropriate privileges. Nonprivileged users can import only their own login context; privileged users can import the login contexts created by any users. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. ERRORS sec_login_s_context_invalid The login context itself is not valid. sec_login_s_default_use Illegal use of the default login handle occurred. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_login_export_context 4 sec_login_init_first NAME sec_login_init_first - Initializes the default context SYNOPSIS #include void sec_login_init_first( error_status_t *status); PARAMETERS Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_login_init_first() routine initializes the default context inheritance mechanism. If the default inheritance mechanism is already initialized, the operation fails. Typically, this routine is called by the initial process at machine boot time to initialize the default context inheritance mechanism for the host machine process hierarchy. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. ERRORS sec_login_s_default_use The default context is already initialized. sec_login_s_privileged An unprivileged process was called in. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_login_setup_first sec_login_validate_first 4 sec_login_inquire_net_info NAME sec_login_inquire_net_info - Returns a principal's network information SYNOPSIS #include void sec_login_inquire_net_info( sec_login_handle_t login_context, sec_login_net_info_t *net_info, error_status_t *status); PARAMETERS Input login_context An opaque handle to the login context for the desired principal. (See sec_intro for more details about the login context.) Output net_info A pointer to the returned sec_login_net_info_t data structure that contains the principal's network information. The sec_login_net_info_t structure is defined as follows: typedef struct { sec_id_pac_t pac; unsigned32 acct_expiration_date; unsigned32 passwd_expiration_date; unsigned32 identity_expiration_date; } sec_login_net_info_t; }; status A pointer to the completion status. On successful completion, the routine returns one of the following status codes: + error_status_ok to indicate that the principal's network information returned in the sec_login_net_info_t data structure has been validated and certified. + sec_login_s_not_certified to indicate that the principal's network information returned in the sec_login_net_info_t data structure has been validated, but not certified. Although this code indicates successful completion, it warns you that the information is not validated. If the call does not complete successfully, it returns an error. DESCRIPTION The sec_login_inquire_net_info() routine returns network information for the principal identified by the specified login context. The network information consists of the following: + The Privilege Attribute Certificate (PAC) that describes the identity and group memberships of the principal. + The expiration date for the principal's account in the DCE Registry. + The expiration date for the principal's password in the DCE Registry. + The lifetime for the principal's authenticated network identity. This is the lifetime of the principal's TGT (see the sec_login_get_expiration() routine). A value of 0 (zero) for an expiration date means there is no expiration date. In other words, the principal's account, password, or authenticated identity is good indefinitely. To remove the returned net_info structure when it is no longer needed, use sec_login_free_net_info(). FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. ERRORS sec_login_s_not_certified The login context is not certified. sec_login_s_context_invalid The login context is not valid. sec_login_s_no_current_context The default context was specified, but none exists. sec_login_s_auth_local Operation not valid on local context. The call's identity was not authenticated. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_login_get_expiration sec_login_free_net_info 4 sec_login_newgroups NAME sec_login_newgroups - Changes the group list for a login context SYNOPSIS #include boolean32 sec_login_newgroups( sec_login_handle_t login_context, sec_login_flags_t flags, unsigned32 num_local_groups, sec_id_t local_groups[], sec_login_handle_t *restricted_context, error_status_t *status); PARAMETERS Input login_context An opaque handle to login context data. The login context contains, among other data, the account principal name and UUID, account restrictions, records of group membership, and the process home directory. (See sec_intro for more details about the login context.) flags A set of flags of type sec_login_flags_t. These contain information about how the new network credentials will be used. Currently, the only flag used is sec_login_credentials_private, that, when set, implies that the new context is only to be used by the calling process. If this flag is not set (flags = sec_login_no_flags), descendants of the calling process may also use the new network credentials. num_local_groups An unsigned 32-bit integer containing the number of local group identities to include in the new context. local_groups[] An array of sec_id_t elements. Each element contains the UUID of a local group identity to include in the new context. These identities are local to the cell. Optionally, each element may also contain a pointer to a character string containing the name of the local group. Output restricted_context An opaque handle to the login context containing the changed group list. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_login_newgroups() routine changes the group list for the specified login context. Part of a network identity is a list of the various groups to which a principal belongs. The groups are used to determine a user's access to various objects and services. This routine returns a new login context that contains the changed group list. To remove the new login context when it is no longer needed, use sec_login_purge_context(). This operation does not need to be validated as the user identity does not change. Consequently, knowledge of the password is not needed. NOTES urrently you can have only groups from the local cell. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. RETURN VALUES This routine returns TRUE when the new login context is successfully established. ERRORS sec_login_s_auth_local Operation not valid on local context. sec_login_s_default_use It is an error to try to certify the default context. sec_login_s_groupset_invalid The input list of group names is invalid. There may be groups to which the caller does not belong, or the list may contain groups that do not exist. error_status_ok The call was successful. EXAMPLES The following example illustrates use of the sec_login_newgroups() routine as part of a process to change the groupset: sec_login_get_current_context(&login_context, &st); sec_login_get_groups(login_context, &num_groups, &groups, &st); ...the group IDs have to be converted from the returned UNIX numbers into UUIDs (use sec_rgy_pgo_unix_num_to_id)... for (i=0; i < num_groups; i++) { ... query whether the user wants to discard any of the current group memberships. Copy new groupset to the new_groups array ... } if ( !sec_login_newgroups(sec_login_no_flags, num_new_groups, new_groups, &login_context, &st)) { if (st == sec_login_s_groupset_invalid) printf("New groupset invalid0); ... application specific error handling ... } RELATED INFORMATION Functions: sec_intro sec_login_get_groups sec_login_purge_context 4 sec_login_purge_context NAME sec_login_purge_context - Destroys a login context and frees its storage SYNOPSIS #include void sec_login_purge_context( sec_login_handle_t *login_context, error_status_t *status); PARAMETERS Input login_context A pointer to an opaque handle to login context data. The login context contains, among other data, the account principal name and UUID, account restrictions, records of group membership, and the process home directory. (See sec_intro for more details about the login context.) Note that a pointer to the handle is submitted, so the handle may be reset to NULL upon successful completion. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_login_purge_context() routine frees any storage allocated for the specified login context and destroys the associated network credentials, if any exist. CAUTIONS Applications must be cautious when purging the current context as this destroys network credentials for all processes that share the credentials. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. ERRORS sec_login_s_default_use Illegal use of the default login handle occurred. sec_login_s_context_invalid The login context itself is not valid. error_status_ok The call was successful. EXAMPLES The following example illustrates use of the sec_login_purge_context() routine as part of a straightforward login process: if (sec_login_setup_identity( user_name, sec_login_no_flags, &login_context, &st)) { ... get password from user... if (sec_login_validate_identity(login_context, password, &reset_passwd, &auth_src, &st)) { if (!sec_login_certify_identity(login_context, &st)) exit(error_wierd_auth_svc); sec_login_set_context(login_context, &st); if (auth_src != sec_login_auth_src_network) printf("no network credentials"); if (reset_passwd) { ... get new password from user, reset registry record ... }; sec_login_get_pwent(login_context, &pw_entry, &st); if (pw_entry.pw_expire < todays_date) { sec_login_purge_context(&login_context, &st); exit(0) } ... any other application specific login valid actions ... } } else { sec_login_purge_context(&login_context, &st); ... application specific login failure actions ... } } RELATED INFORMATION Functions: sec_intro sec_login_set_context sec_login_setup_identity sec_login_validate_identity 4 sec_login_refresh_identity NAME sec_login_refresh_identity - Refreshes an authenticated identity for a login context SYNOPSIS #include boolean32 sec_login_refresh_identity( sec_login_handle_t login_context, error_status_t *status); PARAMETERS Input login_context An opaque handle to login context data. The login context contains, among other data, the account principal name and UUID, account restrictions, records of group membership, and the process home directory. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_login_refresh_identity() routine refreshes a previously established identity. It operates on an existing valid context, and cannot be used to change credentials associated with that identity. The refreshed identity reflects changes that affect ticket lifetimes, but not other changes. For example, the identity will reflect a change to maximum ticket lifetime, but not the addition of the identity as a member to a group. Only a DCE login reflects all administrative changes made since the last login. The refreshed identity must be validated with sec_login_validate_identity() before it can be used. It is an error to refresh a locally authenticated context. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. ERRORS sec_login_s_context_invalid The login context itself is not valid. sec_login_s_default_use Illegal use of the default login handle occurred. sec_login_s_no_memory Not enough memory is available to complete the operation. error_status_ok The call was successful. EXAMPLES Since the authenticated network identity for a process has a finite lifetime, there is a risk it will expire during some long network operation, preventing the operation from completing. For a server application that must run with an authenticated network identity because they themselves sometimes act as clients of another server, the sec_login calls can be used to check the network identity expiration date, run sec_login_refresh_identity and sec_login_validate_identity before the expiration. This will prevent interruptions in the server's operation due to the restrictions in network access applied to an unauthenticated identity. sec_login_get_expiration(login_context, &expire_time, &st); if (expire_time < (current_time + operation_duration)) { if (!sec_login_refresh_identity(login_context, &st)) { ... login context cannot be renewed ... ... sleep and try again .... } } else { if (sec_login_validate_identity(login_context, password, &reset_passwd, &auth_src, &st)) { ... identity validated ... } else { ... validation failed ... exit(error_validation_failure); } } } operation(); RELATED INFORMATION Functions: sec_intro sec_login_validate_identity 4 sec_login_release_context NAME sec_login_release_context - Frees storage allocated for a login context SYNOPSIS #include void sec_login_release_context( sec_login_handle_t *login_context, error_status_t *status); PARAMETERS Input/Output login_context A pointer to an opaque handle to login context data. The login context contains, among other data, the account principal name and UUID, account restrictions, records of group membership, and the process home directory. (See sec_intro for more details about the login context.) Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_login_release_context() routine frees any memory allocated for a login context. Unlike sec_login_purge_context(), it does not destroy the associated network credentials that still reside in the credential cache. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. ERRORS sec_login_s_default_use Illegal use of the default login handle occurred. sec_login_s_context_invalid The login context itself is invalid. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_login_purge_context 4 sec_login_set_context NAME sec_login_set_context - Creates network credentials for a login context SYNOPSIS #include void sec_login_set_context( sec_login_handle_t login_context, error_status_t *status); PARAMETERS Input login_context An opaque handle to login context data. The login context contains, among other data, the account principal name and UUID, account restrictions, records of group membership, and the process home directory. (See sec_intro for more details about the login context.) Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_login_set_context() routine sets the network credentials to those specified by the login context. This context must have been previously validated. Contexts acquired through sec_login_get_current_context() or sec_login_newgroups() do not need to be validated since those routines return previously alidated contexts. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. ERRORS sec_login_s_context_invalid The login context itself is invalid. sec_login_s_default_use Illegal use of the default login handle occurred. sec_login_s_auth_local Operation not valid on local context. error_status_ok The call was successful. EXAMPLES The following example illustrates use of the sec_login_set_context() routine as part of a straightforward login process: if (sec_login_setup_identity( user_name, sec_login_no_flags, &login_context, &st )) { ... get password from user... if (sec_login_validate_identity(login_context, password, &reset_passwd, &auth_src, &st)) { if (!sec_login_certify_identity(login_context, &st)) exit(error_weird_auth_svc); sec_login_set_context(login_context, &st); if (auth_src != sec_login_auth_src_network) printf("no network credentials"); if (reset_passwd) { ... get new password from user, reset registry record ... }; sec_login_get_pwent(login_context, &pw_entry, &st); if (pw_entry.pw_expire < todays_date) { sec_login_purge_context(&login_context, &st); exit(0) } ... any other application specific login valid actions ... } } else { sec_login_purge_context(&login_context, &st); ... application specific login failure actions ... } } RELATED INFORMATION Functions: sec_intro sec_login_setup_identity sec_login_validate_identity 4 sec_login_set_extended_attrs NAME sec_login_set_extended_attrs - Constructs a new login context that contains extended registry attributes SYNOPSIS #include sec_login_handle_t sec_login_set_extended_attrs( sec_login_handle_t my_login_context, unsigned32 num_attributes, sec_attr_t attributes[] error_status_t *status); PARAMETERS Input my_login_context A value of sec_login_handle_t that provides an opaque handle to the identity of the calling client. num_attributes An unsigned 32-bit integer that specifies the number of elements in the attributes[] array. The number must be greater than 0. attributes[] An array of values of type sec_attr_t that specifies the list of attributes to be set in the new login context. Output status A pointer to the completion status. On successful completion, status is assigned error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_login_set_extended_attrs() constructs a login context that contains extended registry attributes that have been established for the object identified by my_login_context. The attributes themselves must have been established and attached to the object using the Extended Registry Attribute API. The input attributes[] array of sec_attr_t values should specify the attr_id field for each requested attribute. Since the lookup is by attribute type ID only, set the attribute.attr_value.attr_encoding field to sec_attr_enc_void for each attribute. Note that sec_attr_t is an Extended Registry Attribute data type. For more information on Extended Registry Attributes, see the description of the sec_attr calls in this document and the chapter titled "The Extended Registry Attribute API" in the DCE Application Development Guide. You cannot use this call to add extended registry attributes to a delegation chain. If you pass in a login context that refers to a delegation chain, an invalid context error will be returned. The routine returns a new login context of type sec_login_handle_t that includes the attributes specified in the attributes[] array. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. ERRORS sec_login_s_invalid_context error_status_ok RELATED INFORMATION Functions: sec_intro sec_rgy_attr_... calls sec_login_become_impersonator sec_login_setup_identity sec_login_validate_identity sec_login_set_context 4 sec_login_setup_first NAME sec_login_setup_first - Sets up the default network context SYNOPSIS #include boolean32 sec_login_setup_first( sec_login_handle_t *init_context, error_status_t *status); PARAMETERS Output init_context A pointer to an opaque handle to login context data. The login context contains, among other data, the account principal name and UUID, account restrictions, records of group membership, and the process home directory. In this call, the context will be that of the host machine initial process. (See sec_intro for more details about the login context.) status A pointer to the completion status. On successful completion, status is assigned error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_login_setup_first() routine sets up the default context network identity. If the default context already contains valid credentials, the routine fails. Typically, this routine is called from the Security Validation Service of the dced process to breathe life into the default credentials for the host machine process hierarchy. This routine uses the hostname available via the local dce_config interface as the principal name for the setup, so it does need a principal name as input. RETURN VALUES The routine returns a boolean32 value that is TRUE if the setup was successful, and FALSE otherwise. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. ERRORS sec_login_s_default_use The default context is already in use and does not need to be set up again. sec_login_s_no_current_context The calling process has no context of its own. sec_login_s_privileged An unprivileged process was called in. sec_login_s_config The DCE configuration (dce_config) information is not available. sec_rgy_object_not_found The principal does not exist. sec_rgy_server_unavailable The network registry is not available. sec_login_s_no_memory A memory allocation error occurred. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_login_init_first sec_login_validate_first 4 sec_login_setup_identity NAME sec_login_setup_identity - Sets up the user's network identity SYNOPSIS #include boolean32 sec_login_setup_identity( unsigned_char_p_t principal, sec_login_flags_t flags, sec_login_handle_t *login_context, error_status_t *status); PARAMETERS Input principal A pointer (type unsigned_char_p_t) indicating a character string containing the principal name on the registry account corresponding to the calling process. flags A set of flags of type sec_login_flags_t. These contain information about how the new network credentials are to be used. Output login_context A pointer to an opaque handle to login context data. The login context contains, among other data, the account principal name and UUID, account restrictions, records of group membership, and the process home directory. (See sec_intro for more details about the login context.) status A pointer to the completion status. On successful completion, status is assigned error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_login_setup_identity() routine creates any local context necessary to perform authenticated network operations. It does not establish any local operating system context; that is the responsibility of the caller. It is the standard network login function. The network identity set up by this operation cannot be used until it is validated via sec_login_validate_identity(). The sec_login_setup_identity() operation and the sec_login_validate_identity() operation are two halves of a single logical operation. Together they collect the identity data needed to establish an authenticated identity. NOTES Neither sec_login_setup_identity() nor sec_login_validate_identity() check for account or identity expiration. The application program using this interface is responsible for such checks. RETURN VALUES The routine returns TRUE if the identity has been successfully established. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. ERRORS sec_rgy_object_not_found The principal does not exist. sec_rgy_server_unavailable The network registry is not available. sec_login_s_no_memory Not enough memory is available to complete the operation. error_status_ok The call was successful. EXAMPLES The following example illustrates use of the sec_login_setup_identity() routine as part of a straightforward login process: if (sec_login_setup_identity( user_name, sec_login_no_flags, &login_context, &st )) { ... get password from user... if (sec_login_validate_identity(login_context, password, &reset_passwd, &auth_src, &st)) { if (!sec_login_certify_identity(login_context, &st)) exit(error_weird_auth_svc); sec_login_set_context(login_context, &st); if (auth_src != sec_login_auth_src_network) printf("no network credentials"); if (reset_passwd) { ... get new password from user, reset registry record ... }; sec_login_get_pwent(login_context, &pw_entry, &st); if (pw_entry.pw_expire < todays_date) { sec_login_purge_context(&login_context, &st); exit(0) } ... any other application specific login valid actions ... } } else { sec_login_purge_context(&login_context, &st); ... application specific login failure actions ... } } RELATED INFORMATION Functions: sec_intro sec_login_validate_identity sec_login_set_context 4 sec_login_valid_and_cert_ident NAME sec_login_valid_and_cert_ident - Validates and certifies a login context SYNOPSIS #include boolean32 sec_login_valid_and_cert_ident( sec_login_handle_t login_context, sec_passwd_rec_t *passwd, boolean32 *reset_passwd, sec_login_auth_src_t *auth_src, error_status_t *status); PARAMETERS Input login_context An opaque handle to login context data. The login context contains, among other data, the account principal name and UUID, account restrictions, records of group membership, and the process home directory. (See sec_intro for more details about the login context.) passwd A password record to be checked against the password in the principal's registry account. The routine returns TRUE if the two match. The contents of the passwd parameter are erased after the call has finished processing it. Output reset_passwd A pointer to a 32-bit boolean32 value. The routine returns TRUE if the account password has expired and must be reset. auth_src A 32-bit set of flags identifying the source of the authentication. Upon return after successful authentication, the flags in auth_src indicate what authority was used to validate the login context. If the authentication was accomplished with the network authority, the sec_login_auth_src_network flag is set, and the process login context has credentials to use the network. If the authentication was accomplished with local data only (either the principal's account is tailored for the local machine with overrides, or the network authority is unavailable), the sec_login_auth_src_local flag is set. Login contexts that are authenticated locally may not be used to establish network credentials because they have none. status A pointer to the completion status. On successful completion, status is assigned error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_login_valid_and_cert_ident() routine validates and certifies a login context established with sec_login_setup_identity(). The caller must supply the user's password as input with the passwd parameter. This routine combines the operations of the sec_login_validate_identity() and sec_login_certify_identity() routines. It is intended for use by system login programs that need to extract trustworthy operating system credentials for use in setting the local identity for a process. This operation destroys the contents of the passwd input parameter. If the network security service is unavailable or if the user's password has been overridden on the host, a locally authenticated context is created, and the auth_src parameter is set to sec_login_auth_src_local. Data extracted from a locally authenticated context may be used to set the local OS identity, but it cannot be used to establish network credentials. This routine is a privileged operation. RETURN VALUES The routine returns TRUE if the login identity has been successfully validated. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. ERRORS sec_rgy_passwd_invalid The input string does not match the account password. sec_rgy_server_unavailable The DCE Registry Server is unavailable. sec_login_s_acct_invalid The account is invalid or has expired. sec_login_s_privileged This is a privileged operation and was invoked by an unprivileged process. sec_login_s_null_password The input string is NULL. sec_login_s_default_use The input context was the default context, which cannot be validated. sec_login_s_already_valid The login context has already been validated. sec_login_s_unsupp_passwd_type The password type is not supported. sec_login_s_no_memory Not enough memory is available to complete the operation. sec_login_s_preauth_failed Preauthentication failure. error_status_ok The call was successful. EXAMPLES The following example illustrates use of the sec_login_valid_and_cert_ident() routine as part of a system login process: if (sec_login_setup_identity(, sec_login_no_flags, &login_context, &st)) { ... get password ... if (sec_login_valid_and_cert_ident(login_context, password, &st)) { if (auth_src == sec_login_auth_src_network) { if (GOOD_STATUS(&st) sec_login_set_context(login_context); } } if (reset_passwd) { ... reset the user's password ... if (passwd_reset_fails) { sec_login_purge_context(login_context) ... application login failure actions ... } ... application specific login valid actions ... } } RELATED INFORMATION Functions: sec_intro sec_login_certify_identity sec_login_setup_identity sec_login_validate_identity 4 sec_login_valid_from_keytable NAME sec_login_valid_from_keytable - Validates a login context's identit using input from a specified keytable file SYNOPSIS #include boolean32 sec_login_valid_from_keytable( sec_login_handle_t login_context, unsigned32 authn_service, void *arg, unsigned32 try_kvno, unsigned32 *used_kvno, boolean32 *reset_passwd, sec_login_auth_src_t *auth_src, error_status_t *status); PARAMETERS Input login_context An opaque handle to login context data. The login context contains, among other data, the account principal's name and UUID, account restrictions, records of the account principal's group memberships, and the account's home directory. (See sec_intro for more details about the login context.) authn_service Identifies the authentication protocol using the key. The possible authentication protocols are as follows: rpc_c_authn_dce_secret DCE shared-secret key authentication. rpc_c_authn_dce_public DCE public key authentication (reserved for future use). arg This parameter can specify either the local keytab file or an argument to the get_key_fn key acquisition routine of the rpc_server_register_auth_info routine. A value of NULL specifies that the default keytab file should be used. A keytab file name specifies that that file should be used as the keytab file. You must prepend the file's absolute filename with FILE: and the file must have been created with the rgy_edit command or the sec_key_mgmt_set_key routine. Any other value specifies an argument for the get_key_fn key acquisition routine. See the rpc_server_register_auth_info() reference page for more information. try_kvno The version number of the key in the keytab file to try first. Specify NULL to try the current version of the key. Output used_kvno A pointer to a 32-bit boolean32 value that specifies the version number of the the key from the keytab file that was used to successfully validate the login context, if any. reset_passwd A pointer to a 32-bit boolean32 value. The routine returns TRUE if the account password has expired and should be reset. auth_src How the the login context was authorized. The sec_login_auth_src_t data type distinguishes the various ways the login context was authorized. There are three possible values: sec_login_auth_src_network Authentication accomplished through the normal network authority. A login context authenticated this way will have all the network credentials it ought to have. sec_login_auth_src_local Authentication accomplished via local data. Authentication occurs locally if a principal's account is tailored for the local machine, or if the network authority is unavailable. Since a login contexts authenticated locally has no network credentials, it can not be used for network operations. sec_login_auth_src_overridden Authentication accomplished via the override facility. status A pointer to the completion status. On successful completion, status is assigned error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_login_valid_from_keytable () routine validates the login context established with sec_login_setup_identity(). The sec_login_valid_from_keytable () routine obtains the principal's password from the specified keytable. If try_kvno specifies a key version number, that version number key is tried first, otherwise the current key version number is tried first. The function trys all keys in the keytable until it finds one that validates the login context. This operation must be invoked before the network credentials can be used. NOTES A context is not secure and must not be set or exported until the authentication service is itself authenticated with the sec_login_certify_identity() call. RETURN VALUES The routine returns TRUE if the login context has been successfully validated. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. ERRORS sec_rgy_passwd_invalid The input string does not match the account password. sec_rgy_server_unavailable There is no data with which to compare the input string. sec_login_s_acct_invalid The account is invalid or has expired. sec_login_s_default_use The input context was the default context, which cannot be validated. sec_login_s_already_valid The login context has already been validated. sec_login_s_unsupp_passwd_type The password type is not supported. sec_key_mgmt_e_key_unavailable The requested key is not present. sec_key_mgmt_e_authn_invalid The authentication protocol is not valid. sec_key_mgmt_e_unauthorized The caller is not authorized to perform the operation. sec_s_no_memory Unable to allocate memory. error_status_ok The call was successful. EXAMPLES The following example illustrates use of the sec_login_valid_from_keytable() routine as part of a straightforward login process: if (sec_login_setup_identity( user_name, sec_login_no_flags, &login_context, &st )) { ... get password from local keytable... if (sec_login_valid_from_keytable( login_context, authn_service, arg, try_kvno, &used_kvno, &reset_passwd, &auth_src, &st )) { sec_login_set_context(login_context, &st); if (auth_src != sec_login_auth_src_network) printf("no network credentials"); } ... any other application specific login valid actions ... } } else { sec_login_purge_context(&login_context, &st); ... application specific login failure actions ... } } RELATED INFORMATION Functions: sec_intro sec_login_validate_identity sec_login_certify_identity sec_login_setup_identity sec_login_valid_and_cert_ident 4 sec_login_validate_first NAME sec_login_validate_first - Validates the initial login context SYNOPSIS #include boolean32 sec_login_validate_first( sec_login_handle_t init_context, boolean32 *reset_passwd, sec_login_auth_src_t *auth_src, error_status_t *status); PARAMETERS Input init_context An opaque handle to login context data. The login context contains, among other data, the account principal name and UUID, account restrictions, records of group membership, and the process home directory. In this call, the context will be that of the host machine initial process. (See sec_intro for more details about the login context.) Output reset_passwd A pointer to a 32-bit boolean32 value. The routine returns TRUE if the account password has expired and must be reset. auth_src A 32-bit set of flags identifying the source of the authentication. Upon return after successful authentication, the flags in auth_src indicate what authority was used to validate the login context. If the authentication was accomplished with the network authority, the sec_login_auth_src_network flag is set, and the process login context has credentials to use the network. If the authentication was accomplished with local data only (either the principal's account is tailored for the local machine with overrides, or the network authority is unavailable), the sec_login_auth_src_local flag is set. Login contexts that are authenticated locally may not be used to establish network credentials because they have none. status A pointer to the completion status. On successful completion, status is assigned error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_login_validate_first() routine validates the default login context established via sec_login_setup_first(). Typically, this operation is called from the Security Validation Service of the dced process to validate the default credentials for the host machine process hierarchy. This operation uses the password for the local host, and therefore does not require a password parameter. RETURN VALUES The routine returns a boolean32 value that is TRUE if the setup was successful, and FALSE otherwise. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. ERRORS sec_login_s_privileged An unprivileged process was called in. sec_rgy_server_unavailable The network authentication service was unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_login_init_first sec_login_setup_first 4 sec_login_validate_identity NAME sec_login_validate_identity - Validates a login context's identity SYNOPSIS #include boolean32 sec_login_validate_identity( sec_login_handle_t login_context, sec_passwd_rec_t *passwd, boolean32 *reset_passwd, sec_login_auth_src_t *auth_src, error_status_t *status); PARAMETERS Input login_context An opaque handle to login context data. The login context contains, among other data, the account principal name and UUID, account restrictions, records of group membership, and the process home directory. (See sec_intro for more details about the login context.) passwd A password record to be checked against the password in the principal's registry account. The routine returns TRUE if the two match. The contents of the passwd parameter are erased after the call has finished processing it. Output reset_passwd A pointer to a 32-bit boolean32 value. The routine returns TRUE if the account password has expired and must be reset. auth_src How the the login context was authorized. The sec_login_auth_src_t data type distinguishes the various ways the login context was authorized. There are three possible values: sec_login_auth_src_network sec_login_auth_src_local sec_login_auth_src_overridden status A pointer to the completion status. On successful completion, status is assigned error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_login_validate_identity() routine validates the login context established with sec_login_setup_identity(). This operation must be invoked before the network credentials can be used. The caller must supply the user's password in a sec_passwd_rec_t as input with the passwd parameter. The following example sets up a plaintext password for the passwd parameter: sec_passwd_str_t tmp_passwd; passwd.version_number = sec_passwd_c_version_none; passwd.pepper = NULL; passwd.key.key_type = sec_passwd_plain; strncpy( (char *) tmp_passwd, (char *) my_passwd, sec_passwd_str_max_len ); tmp_passwd[sec_passwd_str_max_len] = ' '; passwd_rec.key.tagged_union.plain = &(tmp_passwd[0]); When a network identity is set, only state information for network operations has been established. The local operating system identity has not been modified. It is the responsibility of the caller to establish any local operating identity state. The sec_login_setup_identity() operation and the sec_login_validate_identity() operation are two halves of a single logical operation. Together they collect the identity data needed to establish an authenticated identity. The operations are independent so the user's password need not be sent across the network. The identity validation performed by sec_login_validate_identity() is a local operation. NOTES A context is not secure and must not be set or exported until the authentication service is itself authenticated with the sec_login_certify_identity() call. System login programs that set local operating system identity using data extracted from a login context should use sec_login_valid_and_cert_ident() instead of sec_login_validate_identity(). If the Security server and client clocks are not synchronized to within 2 to 3 minutes of each other, this call can return a password validation error. RETURN VALUES The routine returns TRUE if the login identity has been successfully validated. FILES SYS$COMMON:[DCE$LIBRARY]SEC_LOGIN.IDL The idl file from which dce/sec_login.h was derived. ERRORS sec_rgy_passwd_invalid The input string does not match the account password. sec_rgy_server_unavailable There is no data with which to compare the input string. sec_login_s_acct_invalid The account is invalid or has expired. sec_login_s_null_password The input string is NULL. sec_login_s_default_use The input context was the default context, which cannot be validated. sec_login_s_already_valid The login context has already been validated. sec_login_s_unsupp_passwd_type The password type is not supported. sec_login_s_no_memory Not enough memory is available to complete the operation. sec_login_s_preauth_failed Preauthentication failure. error_status_ok The call was successful. EXAMPLES The following example illustrates use of the sec_login_validate_identity() routine as part of a straightforward login process: if (sec_login_setup_identity( user_name, sec_login_no_flags, &login_context, &st )) { ... get password from user... if (sec_login_validate_identity(login_context, password, &reset_passwd, &auth_src, &st)) { if (!sec_login_certify_identity(login_context, &st)) exit(error_weird_auth_svc); sec_login_set_context(login_context, &st); if (auth_src != sec_login_auth_src_network) printf("no network credentials"); if (reset_passwd) { ... get new password from user, reset registry record ... }; sec_login_get_pwent(login_context, &pw_entry, &st); if (pw_entry.pw_expire < todays_date) { sec_login_purge_context(&login_context, &st); exit(0) } ... any other application specific login valid actions ... } } else { sec_login_purge_context(&login_context, &st); ... application specific login failure actions ... } } RELATED INFORMATION Functions: sec_intro sec_login_certify_identity sec_login_setup_identity sec_login_valid_and_cert_ident 4 sec_pwd_mgmt_free_handle NAME sec_pwd_mgmt_free_handle - Frees storage allocated for a password management handle SYNOPSIS #include void sec_pwd_mgmt_free_handle( sec_pwd_mgmt_handle_t *pwd_mgmt_h, error_status_t *stp ) PARAMETERS Input/Output pwd_mgmt_h A handle to the password management data which is to be freed. Output stp A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_pwd_mgmt_free_handle() routine frees any memory allocated for the contents of a password management handle. FILES SYS$COMMON:[DCE$LIBRARY]SEC_PWD_MGMT.IDL The idl file from which dce/sec_pwd_mgmt.h was derived. ERRORS error_status_ok The call was successful RELATED INFORMATION Functions: sec_intro sec_pwd_mgmt_setup 4 sec_pwd_mgmt_gen_pwd NAME sec_pwd_mgmt_gen_pwd - Generate a set of passwords SYNOPSIS #include void sec_pwd_mgmt_gen_pwd( sec_pwd_mgmt_handle_t pwd_mgmt_h, unsigned32 num_pwds, unsigned32 *num_returned, sec_passwd_rec_t gen_pwds[], error_status_t *stp ) PARAMETERS Input pwd_mgmt_h A handle to user's password management data. num_pwds Number of generated passwords requested. Output num_returned Number of generated passwords returned in the gen_pwds[] array. gen_pwds Array of generated passwords. Each generated password is stored in a sec_passwd_rec_t structure. stp A pointer to the completion status. On successful completion, status is assigned error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_pwd_mgmt_gen_pwd() routine retrieves a set of generated passwords from a password management server which is exporting the rsec_pwd_mgmt_gen_pwd() routine. It obtains the binding information to this server from the pwd_mgmt_h handle. FILES SYS$COMMON:[DCE$LIBRARY]SEC_PWD_MGMT.IDL The idl file from which dce/sec_pwd_mgmt.h was derived. ERRORS sec_rgy_era_pwd_mgmt_auth_type The pwd_mgmt_binding ERA must contain authentication information. sec_pwd_mgmt_svr_unavail The password management server is unavailable sec_pwd_mgmt_svr_error Generic error returned from password management server. An administrator should check the password management server's log file for more information. error_status_ok The call was successful Various RPC communication errors can be returned if there are failures when binding to the password management server. RELATED INFORMATION Functions: sec_intro sec_pwd_mgmt_setup pwd_strengthd 4 sec_pwd_mgmt_get_val_type NAME sec_pwd_mgmt_get_val_type - Gets users password validation type SYNOPSIS #include void sec_pwd_mgmt_get_val_type( sec_pwd_mgmt_handle_t pwd_mgmt_h, signed32 *pwd_val_type, error_status_t *stp ) PARAMETERS Input pwd_mgmt_h A handle to a user's password management data. Output pwd_val_type The user's password validation type. This is retrieved from the pwd_val_type ERA. The possible values and their meaning are: (none): the user has no password policy. (user_select): the user must choose his/her own password. (user_can_select): the user can choose his/her own password or request a generated password. (generation_required): the user must use a generated password. stp A pointer to the completion status. On successful completion, stp is assigned error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_pwd_mgmt_get_val_type() routine returns the value of the user's password validation type, as specified by the pwd_val_type ERA. If the ERA does not exist, 0 (none) is returned in pwd_val_type. FILES SYS$COMMON:[DCE$LIBRARY]SEC_PWD_MGMT.IDL The idl file from which dce/sec_pwd_mgmt.h was derived. ERRORS error_status_ok The call was successful Various RPC communication errors can be returned if there are failures when binding to the password management server. RELATED INFORMATION Functions: sec_intro sec_pwd_mgmt_setup 4 sec_pwd_mgmt_setup NAME sec_pwd_mgmt_setup - Sets up the user's password policy information SYNOPSIS #include void sec_pwd_mgmt_setup( sec_pwd_mgmt_handle_t *pwd_mgmt_h, sec_rgy_handle_t context, sec_rgy_login_name_t login_name, sec_login_handle_t your_lc, rpc_binding_handle_t pwd_mgmt_bind_h, error_status_t *stp ) PARAMETERS Input context A registry server handle indicating the desired registry site. login_name The login name of the user. your_lc The login context handle of the user currently logged in. If null is specified, the default login context will be used. pwd_mgmt_bind_h An RPC binding handle to the password management server. Use of this parameter is currently unsupported. The password management server binding handle will be retrieved from the pwd_mgmt_binding ERA. Set this parameter to NULL. Output pwd_mgmt_h A pointer to an opaque handle to password management/policy data. pwd_mgmt_h contains, among other data, the account name, values of password management ERAs, and a binding handle to the password management server. stp A pointer to the completion status. On successful completion, stp is assigned error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_pwd_mgmt_setup() routine collects the data required to perform remote password management calls to the password management server. FILES SYS$COMMON:[DCE$LIBRARY]SEC_PWD_MGMT.IDL The idl file from which dce/sec_pwd_mgmt.h was derived. ERRORS sec_s_no_memory Not enough memory is available to complete the operation. sec_rgy_server_unavailable The network registry is not available. error_status_ok The call was successful RELATED INFORMATION Functions: sec_intro sec_pwd_mgmt_free_handle sec_pwd_mgmt_gen_pwd sec_pwd_mgmt_get_val_type pwd_strengthd 4 sec_rgy_acct_add NAME sec_rgy_acct_add - Adds an account for a login name SYNOPSIS #include void sec_rgy_acct_add( sec_rgy_handle_t context, sec_rgy_login_name_t *login_name, sec_rgy_acct_key_t *key_parts, sec_rgy_acct_user_t *user_part, sec_rgy_acct_admin_t *admin_part, sec_passwd_rec_t *caller_key, sec_passwd_rec_t *new_key, sec_passwd_type_t new_keytype, sec_passwd_version_t *new_key_version, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. login_name A pointer to the account login name. A login name is composed of three character strings, containing the principal, group, and organization (PGO) names corresponding to the account. All three names must be completely specified. key_parts A pointer to the minimum abbreviation allowed when logging in to the account. Abbreviations are not currently implemented and the only legal value is sec_rgy_acct_key_person. user_part A pointer to the sec_rgy_acct_user_t structure containing the user part of the account data. This represents such information as the account password, home directory, and default shell. admin_part A pointer to the sec_rgy_acct_admin_t structure containing the administrative part of an account's data. This information includes the account creation and expiration dates and flags describing limits to the use of privilege attribute certificates, among other information. caller_key A key to use to encrypt new_key for transmission to the registry server. new_key The password for the new account. During transmission to the registry server, it is encrypted with caller_key. new_keytype The type of the new key. The server uses this parameter to decide how to encode new_key if it is sent as plaintext. Output new_key_version The key version number returned by the server. If the client requests a particular key version number (via the version_number field of the new_key input parameter), the server returns the requested version number back to the client. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_acct_add() routine adds an account with the specified login name. The login name is given in three parts, corresponding to the principal, group, and organization names for the account. The key_parts variable specifies the minimum login abbreviation for the account. If the requested abbreviation duplicates an existing abbreviation for another account, the routine supplies the next shortest unique abbreviation and returns this abbreviation in key_parts. Abbreviations are not currently implemented. Permissions Required The sec_rgy_acct_add() routine requires the following permissions on the account (principal) that is to be added: + The m (mgmt_info) permission to change management information. + The a (auth_info) permission to change authentication information. + The u (user_info) permission to change user information. NOTES The constituent principal, group, and organization (PGO) items for an account must be added before the account can be created. (See the sec_rgy_pgo_add() routine). Also, the principal must have been added as a member of the specified group and organization. (See the sec_rgy_pgo_add_member() routine). FILES SYS$COMMON:[DCE$LIBRARY]ACCT.IDL The idl file from which dce/acct.h was derived. ERRORS sec_rgy_not_authorized The client program is not authorized to add an account to the registry. sec_rgy_not_member_group The indicated principal is not a member of the indicated group. sec_rgy_not_member_org The indicated principal is not a member of the indicated organization. sec_rgy_not_member_group_org The indicated principal is not a member of the indicated group or organization. sec_rgy_object exists The account to be added already exists. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_acct_delete sec_rgy_login_get_info sec_rgy_pgo_add sec_rgy_pgo_add_member sec_rgy_site_open 4 sec_rgy_acct_admin_replace NAME sec_rgy_acct_admin_replace - Replaces administrative account data SYNOPSIS #include void sec_rgy_acct_admin_replace( sec_rgy_handle_t context, sec_rgy_login_name_t *login_name, sec_rgy_acct_key_t *key_parts, sec_rgy_acct_admin_t *admin_part, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. login_name A pointer to the account login name. A login name is composed of three character strings, containing the principal, group, and organization (PGO) names corresponding to the account. For the group and organization names, blank strings can serve as wildcards, matching any entry. The principal name must be input. key_parts A pointer to the minimum abbreviation allowed when logging in to the account. Abbreviations are not currently implemented and the only legal value is sec_rgy_acct_key_person. admin_part A pointer to the sec_rgy_acct_admin_t structure containing the administrative part of an account's data. This information includes the account creation and expiration dates and flags describing limits to the use of privilege attribute certificates, among other information, and can be modified only by an administrator. The sec_rgy_acct_admin_t structure contains the following fields: creator The identity of the principal who created this account in sec_rgy_foreign_id_t form. This field is set by the registry server. creation_date The date (sec_timeval_sec_t) the account was created. This field is set by the registry server. last_changer The identity of the principal who last modified any of the account information (user or administrative). This field is set by the registry server. change_date The date (sec_timeval_sec_t) the account was last modified (either user or administrative data). This field is set by the registry server. expiration_date The date (sec_timeval_sec_t) the account will cease to be valid. good_since_date This date (sec_timeval_sec_t) is for Kerberos-style, ticket-granting ticket revocation. Ticket-granting tickets issued before this date will not be honored by authenticated network services. flags Contains administration flags used as part of the administrator's information for any registry account. This field is in sec_rgy_acct_admin_flags_t form. (See sec_intro for a complete description of these flags.) authentication_flags Contains flags controlling use of authentication services. This field is in sec_rgy_acct_auth_flags_t form. (See sec_intro for a complete description of these flags.) Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_acct_admin_replace() routine replaces the administrative information in the account record specified by the input login name. The administrative information contains limitations on the account's use and privileges. It can be modified only by a registry administrator; that is, a user with the admin_info (abbreviated as a) privilege for an account. The key_parts variable identifies how many of the login_name parts to use as the unique abbreviation for the account. If the requested abbreviation duplicates an existing abbreviation for another account, the routine supplies the next shortest unique abbreviation and returns this abbreviation using key_parts. Permissions Required The sec_rgy_acct_admin_replace() routine requires the following permissions on the account principal: + The m (mgmt_info) permission, if flags or expiration_date is to be changed. + The a (auth_info) permission, if authentication_flags or good_since_date is to be changed. NOTES All users need the w (write) privilege in the appropriate ACL entry to modify any account information. FILES SYS$COMMON:[DCE$LIBRARY]ACCT.IDL The idl file from which dce/acct.h was derived. ERRORS sec_rgy_not_authorized The client program is not authorized to change the administrative information for the specified account. sec_rgy_object_not_found The registry server could not find the specified name. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_acct_user_replace sec_rgy_acct_replace_all sec_rgy_acct_lookup 4 sec_rgy_acct_delete NAME sec_rgy_acct_delete - Deletes an account SYNOPSIS #include void sec_rgy_acct_delete( sec_rgy_handle_t context, sec_rgy_login_name_t *login_name, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. login_name A pointer to the account login name. A login name is composed of three character strings, containing the principal, group, and organization (PGO) names corresponding to the account. Only the principal name is required to perform the deletion. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_acct_delete() routine deletes from the registry the account corresponding to the specified login name. Permissions Required The sec_rgy_acct_delete() routine requires the following permissions on the account principal: + The m (mgmt_info) permission to remove management information. + The a (auth_info) permission to remove authentication information. + The u (user_info) permission to remove user information. NOTES Even though the account is deleted, the PGO items corresponding to the account remain. These must be deleted with separate calls to sec_rgy_pgo_delete(). FILES SYS$COMMON:[DCE$LIBRARY]ACCT.IDL The idl file from which dce/acct.h was derived. ERRORS sec_rgy_not_authorized The client program is not authorized to delete the specified account. sec_rgy_object_not_found No PGO item was found with the given name. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_acct_add sec_rgy_pgo_delete 4 sec_rgy_acct_get_projlist NAME sec_rgy_acct_get_projlist - Returns the projects in an account's project list SYNOPSIS #include void sec_rgy_acct_get_projlist( sec_rgy_handle_t context, sec_rgy_login_name_t *login_name, sec_rgy_cursor_t *projlist_cursor, signed32 max_number, signed32 *supplied_number, uuid_t id_projlist[], signed32 unix_projlist[], signed32 *num_projects, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. login_name A pointer to the account login name. A login name is composed of three character strings, containing the principal, group, and organization (PGO) names corresponding to the account. For the group and organization names, blank strings can serve as wildcards, matching any entry. The principal name must be input. max_number The maximum number of projects to be returned by the call. This must be no larger than the allocated size of the projlist[] arrays. Input/Output projlist_cursor An opaque pointer indicating a specific project in an account's project list. The sec_rgy_acct_get_projlist() routine returns the project indicated by projlist_cursor, and advances the cursor to point to the next project in the list. When the end of the list is reached, the routine returns the value sec_rgy_no_more_entries in the status parameter. Use sec_rgy_cursor_reset() to reset the cursor. Output supplied_number A pointer to the actual number of projects returned. This will always be less than or equal to the max_number supplied on input. If there are more projects in the account list, sec_rgy_acct_get_projlist() sets projlist_cursor to point to the next entry after the last one in the returned list. id_projlist[] An array to receive the UUID of each project returned. The size allocated for the array is given by max_number. If this value is less than the total number of projects in the account project list, multiple calls must be made to return all of the projects. unix_projlist[] An array to receive the UNIX number of each project returned. The size allocated for the array is given by max_number. If this value is less than the total number of projects in the account project list, multiple calls must be made to return all of the projects. num_projects A pointer indicating the total number of projects in the specified account's project list. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_acct_get_projlist() routine returns members of the project list for the specified account. It returns the project information in two arrays. The id_projlist[] array contains the UUIDs for the returned projects. The unix_projlist[] array contains the UNIX numbers for the returned projects. The project list cursor, projlist_cursor, provides an automatic place holder in the project list. The sec_rgy_acct_get_projlist() routine automatically updates this variable to point to the next project in the project list. To return an entire project list, reset projlist_cursor with sec_rgy_cursor_reset() on the initial call and then issue successive calls until all the projects are returned. Permissions Required The sec_rgy_acct_get_projlist() routine requires the r (read) permission on the account principal for which the project list data is to be returned. CAUTIONS There are several different types of cursors used in the registry Application Programmer Interface (API). Some cursors point to PGO items, others point to members in a membership list, and others point to account data. Do not use a cursor for one sort of object in a call expecting another sort of object. For example, you cannot use the same cursor on a call to sec_rgy_acct_get_projlist() and sec_rgy_pgo_get_next(). The behavior in this case is undefined. Furthermore, cursors are specific to a server. A cursor pointing into one replica of the registry database is useless as a pointer into another replica. Use sec_rgy_cursor_reset() to refresh a cursor for use with another call or for another server. FILES SYS$COMMON:[DCE$LIBRARY]ACCT.IDL The idl file from which dce/acct.h was derived. ERRORS sec_rgy_no_more_entries The cursor is at the end of the list of projects. sec_rgy_not_authorized The client program is not authorized to see a project list for this principal. sec_rgy_object exists The account to be added already exists. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_cursor_reset sec_rgy_pgo_get_next 4 sec_rgy_acct_lookup NAME sec_rgy_acct_lookup - Returns data for a specified account SYNOPSIS #include void sec_rgy_acct_lookup( sec_rgy_handle_t context, sec_rgy_login_name_t *name_key, sec_rgy_cursor_t *account_cursor, sec_rgy_login_name_t *name_result, sec_rgy_sid_t *id_sid, sec_rgy_unix_sid_t *unix_sid, sec_rgy_acct_key_t *key_parts, sec_rgy_acct_user_t *user_part, sec_rgy_acct_admin_t *admin_part, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_key A pointer to the account login name. A login name is composed of three character strings, containing the principal, group, and organization (PGO) names corresponding to the account. Blank strings serve as wildcards, matching any entry. Input/Output account_cursor An opaque pointer to a specific account in the registry database. If name_key is blank, sec_rgy_acct_lookup() returns information about the account to which the cursor is pointing. On return, the cursor points to the next account in the database after the returned account. If name_key is blank and the account_cursor has been reset with sec_rgy_cursor_reset(), sec_rgy_acct_lookup() returns information about the first account in the database. When the end of the list of accounts in the database is reached, the routine returns the value sec_rgy_no_more_entries in the status parameter. Use sec_rgy_cursor_reset() to refresh the cursor. Output name_result A pointer to the full login name of the account (including all three names) for which the information is returned. The remaining parameters contain the information belonging to the returned account. id_sid A structure containing the three UUIDs of the principal, group, and organization for the account. unix_sid A structure containing the three UNIX numbers of the principal, group, and organization for the account. key_parts A pointer to the minimum abbreviation allowed when logging in to the account. Abbreviations are not currently implemented and the only legal value is sec_rgy_acct_key_person. user_part A pointer to the sec_rgy_acct_user_t structure containing the user part of the account data. This represents such information as the account password, home directory, and default shell, all of which are accessible to, and may be modified by, the account owner. admin_part A pointer to the sec_rgy_acct_admin_t structure containing the administrative part of an account's data. This information includes the account creation and expiration dates and flags describing limits to the use of privilege attribute certificates, among other information, and can be modified only by an administrator. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_acct_lookup() routine returns all the information about an account in the registry database. The account can be specified either with name_key or account_cursor. If name_key is completely blank, the routine uses the account_cursor value instead. For name_key, a zero-length principal, group, or organization key serves as a wildcard. For example, a login name key with the principal and organization fields blank returns the next (possibly first) account whose group matches the input group field. The full login name of the returned account is passed back in name_result. The account_cursor provides an automatic place holder in the registry database. The routine automatically updates this variable to point to the next account in the database, after the account for which the information was returned. If name_key is blank and the account_cursor has been reset with sec_rgy_cursor_reset()*O, sec_rgy_acct_lookup() returns information about the first account in the database. Permissions Required The sec_rgy_acct_lookup() routine requires the r (read) permission on the account principal to be viewed. CAUTIONS There are several different types of cursors used in the registry Application Programmer Interface (API). Some cursors point to PGO items, others point to members in a membership list, and others point to account data. Do not use a cursor for one sort of object in a call expecting another sort of object. For example, you cannot use the same cursor on a call to sec_rgy_acct_get_projlist() and sec_rgy_pgo_get_next(). The behavior in this case is undefined. Furthermore, cursors are specific to a server. A cursor pointing into one replica of the registry database is useless as a pointer into another replica. Use sec_rgy_cursor_reset() to renew a cursor for use with another call or for another server. FILES SYS$COMMON:[DCE$LIBRARY]ACCT.IDL The idl file from which dce/acct.h was derived. ERRORS sec_rgy_no_more_entries The cursor is at the end of the accounts in the registry. sec_rgy_object_not_found The input account could not be found by the registry server. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_cursor_reset sec_rgy_acct_replace_all sec_rgy_acct_admin_replace sec_rgy_acct_user_replace 4 sec_rgy_acct_passwd NAME sec_rgy_acct_passwd - Changes the password for an account SYNOPSIS #include void sec_rgy_acct_passwd( sec_rgy_handle_t context, sec_rgy_login_name_t *login_name, sec_passwd_rec_t *caller_key, sec_passwd_rec_t *new_key, sec_passwd_type_t new_keytype, sec_passwd_version_t *new_key_version, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. login_name A pointer to the account login name. A login name is composed of three character strings, containing the principal, group, and organization (PGO) names corresponding to the account. All three strings must be completely specified. caller_key A key to use to encrypt the key for transmission to the registry server. If communications secure to the rpc_c_authn_level_pkt_privacy level are available on a system, then this parameter is not necessary, and the packet encryption is sufficient to ensure security. new_key The password for the new account. During transmission to the registry server, it is encrypted with caller_key. new_keytype The type of the new key. The server uses this parameter to decide how to encode new_key if it is sent as plaintext. Output new_key_version The key version number returned by the server. If the client requests a particular key version number (via the version_number field of the new_key input parameter), the server returns the requested version number back to the client. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_acct_passwd() routine changes an account password to the input password character string. Wildcards (blank fields) are not permitted in the specified account name; the principal, group, and organization names of the account must be completely specified. Permissions Required The sec_rgy_acct_passwd() routine requires the u (user_info) permission on the account principal whose password is to be changed. FILES SYS$COMMON:[DCE$LIBRARY]ACCT.IDL The idl file from which dce/acct.h was derived. ERRORS sec_rgy_not_authorized The client program is not authorized to change the password of this account. sec_rgy_object_not_found The account to be modified was not found by the registry server. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro 4 sec_rgy_acct_rename NAME sec_rgy_acct_rename - Changes an account login name SYNOPSIS #include void sec_rgy_acct_rename( sec_rgy_handle_t context, sec_rgy_login_name_t *old_login_name, sec_rgy_login_name_t *new_login_name, sec_rgy_acct_key_t *new_key_parts, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. old_login_name A pointer to the current account login name. The login name is composed of three character strings, containing the principal, group, and organization (PGO) names corresponding to the account. All three strings must be completely specified. new_login_name A pointer to the new account login name. Again, all three component names must be completely specified. Input/Output new_key_parts A pointer to the minimum abbreviation allowed when logging in to the account. Abbreviations are not currently implemented and the only legal value is sec_rgy_acct_key_person. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_acct_rename() routine changes an account login name from old_login_name to new_login_name. Wildcards (empty fields) are not permitted in either input name; both the old and new login names must completely specify their component principal, group, and organization names. Note, though, that the principal component in a login name cannot be changed. The new_key_parts variable identifies how many of the new_login_name parts to use as the unique abbreviation for the account. If the requested abbreviation duplicates an existing abbreviation for another account, the routine identifies the next shortest unique abbreviation and returns this abbreviation using new_key_parts. Permissions Required The sec_rgy_acct_rename() routine requires the m (mgmt_info) permission on the account principal to be renamed. NOTES The sec_rgy_acct_rename() routine does not affect any of the registry PGO data. The constituent principal, group, and organization items for an account must be added before the account can be created. (See the sec_rgy_pgo_add routine). Also, the principal must have been added as a member of the specified group and organization. (See the sec_rgy_pgo_add_member routine). FILES SYS$COMMON:[DCE$LIBRARY]ACCT.IDL The idl file from which dce/acct.h was derived. ERRORS sec_rgy_not_authorized The client program is not authorized to make the changes. sec_rgy_object_not_found The account to be modified was not found by the registry server. sec_rgy_name_exists The new account name is already in use by another account. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_acct_add 4 sec_rgy_acct_replace_all NAME sec_rgy_acct_replace_all - Replaces all account data for an account SYNOPSIS #include void sec_rgy_acct_replace_all( sec_rgy_handle_t context, sec_rgy_login_name_t *login_name, sec_rgy_acct_key_t *key_parts, sec_rgy_acct_user_t *user_part, sec_rgy_acct_admin_t *admin_part, boolean32 set_password, sec_passwd_rec_t *caller_key, sec_passwd_rec_t *new_key, sec_passwd_type_t new_keytype, sec_passwd_version_t *new_key_version, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. login_name A pointer to the account login name. A login name is composed of three character strings, containing the principal, group, and organization (PGO) names corresponding to the account. For the group and organization names, blank strings can serve as wildcards, matching any entry. The principal name must be input. user_part A pointer to the sec_rgy_acct_user_t structure containing the user part of the account data. This represents such information as the account password, home directory, and default shell, all of which are accessible to, and may be modified by, the account owner. admin_part A pointer to the sec_rgy_acct_admin_t structure containing the administrative part of an account's data. This information includes the account creation and expiration dates and flags describing limits to the use of privilege attribute certificates, among other information, and can be modified only by an administrator. set_passwd The password reset flag. If you set this parameter to TRUE, the account's password will be changed to the value specified in new_key. caller_key A key to use to encrypt the key for transmission to the registry server. If communications secure to the rpc_c_authn_level_pkt_privacy level are available on a system, then this parameter is not necessary, and the packet encryption is sufficient to ensure security. new_key The password for the new account. During transmission to the registry server, it is encrypted with caller_key. new_keytype The type of the new key. The server uses this parameter to decide how to encode the plaintext key. Input/Output key_parts A pointer to the minimum abbreviation allowed when logging in to the account. Abbreviations are not currently implemented and the only legal value is sec_rgy_acct_key_person. Output new_key_version The key version number returned by the server. If the client requests a particular key version number (via the version_number field of the new_key input parameter), the server returns the requested version number back to the client. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_acct_replace_all() routine replaces both the user and administrative information in the account record specified by the input login name. The administrative information contains limitations on the account's use and privileges. The user information contains such information as the account home directory and default shell. Typically, the administrative information can only be modified by a registry administrator (users with admin_info (a) privileges for an account), while the user information can be modified by the account owner (users with user_info (u) privileges for an account). Use the set_passwd parameter to reset the account password. If you set this parameter to TRUE, the account's pasword is changed to the value specified in new_key. The key_parts variable identifies how many of the login_name parts to use as the unique abbreviation for the replaced account. If the requested abbreviation duplicates an existing abbreviation for another account, the routine identifies the next shortest unique abbreviation and returns this abbreviation using key_parts. Permissions Required The sec_rgy_acct_replace_all() routine requires the following permissions on the account principal: + The m (mgmt_info) permission, if flags or expiration_date is to be changed. + The a (auth_info) permission, if authentication_flags or good_since_date is to be changed. + The u (user_info) permission, if user flags, gecos, homedir (home directory), shell, or passwd (password) are to be changed. NOTES All users need the w (write) privilege to modify any account information. FILES SYS$COMMON:[DCE$LIBRARY]ACCT.IDL The idl file from which dce/acct.h was derived. ERRORS sec_rgy_not_authorized The client program is not authorized to change account information. sec_rgy_object_not_found The specified account could not be found. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_acct_add sec_rgy_acct_admin_replace sec_rgy_acct_rename sec_rgy_acct_user_replace 4 sec_rgy_acct_user_replace NAME sec_rgy_acct_user_replace - Replaces user account data SYNOPSIS #include void sec_rgy_acct_user_replace( sec_rgy_handle_t context, sec_rgy_login_name_t *login_name, sec_rgy_acct_user_t *user_part, boolean32 set_passwd, sec_passwd_rec_t *caller_key, sec_passwd_rec_t *new_key, sec_passwd_type_t new_keytype, sec_passwd_version_t *new_key_version, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. login_name A pointer to the account login name. A login name is composed of three character strings, containing the principal, group, and organization (PGO) names corresponding to the account. For the group and organization names, blank strings can serve as wildcards, matching any entry. The principal name must be input. user_part A pointer to the sec_rgy_acct_user_t structure containing the user part of the account data. This represents such information as the account password, home directory, and default shell, all of which are accessible to, and may be modified by, the account owner. The structure contains the following fields: gecos A character string containing information about the account owner. This often includes such information as their name and telephone number. homedir The default directory upon login for the account. shell The default shell to use upon login. passwd_version_number The password version number, a 32-bit unsigned integer, set by the registry server. passwd_dtm The date and time of the last password change (in sec_timeval_sec_t form), also set by the registry server. flags A flag set of type sec_rgy_acct_user_flags_t. passwd The account's encrypted password. set_passwd The password reset flag. If you set this parameter to TRUE, the user's password will be changed to the value specified in new_key. caller_key A key to use to encrypt the key for transmission to the registry server. If communications secure to the rpc_c_authn_level_pkt_privacy level are available on a system, then this parameter is not necessary, and the packet encryption is sufficient to ensure security. new_key The password for the new account. During transmission to the registry server, it is encrypted with caller_key. new_keytype The type of the new key. The server uses this parameter to decide how to encode the plaintext key. Output new_key_version The key version number returned by the server. If the client requests a particular key version number (via the version_number field of the new_key input parameter), the server returns the requested version number back to the client. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_acct_user_replace() routine replaces the user information in the account record specified by the input login name. The user information contains such information as the account home directory and default shell. Typically, the the user information can be modified by the account owner (users with user_info (u) privileges for an account). Use the set_passwd parameter to reset the user's password. If you set this parameter to TRUE, the user's pasword is changed to the value specified in new_key. Permissions Required The sec_rgy_acct_user_replace() routine requires the u (user_info) permission on the account principal. NOTES All users need the w (write) privilege to modify any account information. FILES SYS$COMMON:[DCE$LIBRARY]ACCT.IDL The idl file from which dce/acct.h was derived. ERRORS sec_rgy_not_authorized The client program is not authorized to modify the account data. sec_rgy_object_not_found The specified account could not be found. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_acct_add sec_rgy_acct_admin_replace sec_rgy_acct_rename sec_rgy_acct_replace_all 4 sec_rgy_attr_cursor_alloc NAME sec_rgy_attr_cursor_alloc - Allocates resources to a cursor used by the sec_rgy_attr_lookup_by_id call SYNOPSIS #include void sec_rgy_attr_cursor_alloc( sec_attr_cursor_t *cursor, error_status_t *status); PARAMETERS Output cursor A pointer to a sec_attr_cursor_t. status A pointer to the completion status. On successful completion, the call returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_attr_cursor_alloc() call allocates resources to a cursor used with the sec_rgy_attr_lookup_by_id call. This routine, which is a local operation, does not initialize cursor. The sec_rgy_attr_cursor_init() routine, which makes a remote call, allocates and initializes the cursor. In addition, sec_rgy_attr_cursor_init() returns the total number of attributes attached to the object as an output parameter; sec_rgy_attr_cursor_alloc() does not. Permissions Required None FILES SYS$COMMON:[DCE$LIBRARY]SEC_ATTR_BASE.IDL The idl file from which dce/sec_attr_base.h was derived. ERRORS no such object error_status_ok RELATED INFORMATION Functions: sec_intro sec_rgy_attr_cursor_init sec_rgy_attr_cursor_release sec_rgy_attr_cursor_reset sec_rgy_attr_lookup_by_id 4 sec_rgy_attr_cursor_init NAME sec_rgy_attr_cursor_init - Initialize a cursor used by the sec_rgy_attr_lookup_by_id call SYNOPSIS #include void sec_rgy_attr_cursor_init ( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, sec_rgy_name_t name, unsigned32 *cur_num_attrs, sec_attr_cursor_t *cursor, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain A value of type sec_rgy_domain_t that identifies the registry domain in which the object specified by name resides. The valid values are as follows: sec_rgy_domain_person The name identifies a principal. sec_rgy_domain_group The name identifies a group. sec_rgy_domain_org The name identifies an organization. This parameter is ignored if name is policy or replist. name A pointer to a sec_rgy_name_t character string containing the name of the person, group, or organization to which the attribute to be scanned is attached. Output cur_num_attrs A pointer to an unsigned 32-bit integer that specifies the number of attributes currently attached to the object. cursor A pointer to a sec_rgy_cursor_t positioned at the first attribute in the list of the object's attributes. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_attr_cursor_init() routine initializes a cursor of type sec_attr_cursor_t (used with the sec_rgy_attr_lookup_by_id call) and initializes the cursor to the first attribute in the specified object's list of attributes. This call also supplies the total number of attributes attached to the object as part of its output. The cursor allocation is a local operation. The cursor initialization is a remote operation and makes a remote call to the Registry. Use the sec_rgy_attr_cursor_release() call to release all resources allocated to a sec_attr_cursor_t cursor. Permissions Required The sec_rgy_attr_cursor_init() routine requires at least one permission (of any type) on the person, group, or organization to which the attribute to be scanned is attached. ERRORS no such object error_status_ok RELATED INFORMATION Functions: sec_intro sec_rgy_attr_lookup_by_id sec_rgy_attr_cursor_release 4 sec_rgy_attr_cursor_release NAME sec_rgy_attr_cursor_release - Release a cursor of typesec_attr_cursor_t that was allocated with the sec_rgy_attr_cursor_init() or sec_rgy_attr_cursor_alloc() call SYNOPSIS #include void sec_rgy_attr_cursor_release ( sec_attr_cursor_t *cursor, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. Input/Output *cursor As an input parameter, a pointer to an uninitialized cursor of type sec_attr_cursor_t. As an output parameter, a pointer to an uninitialized cursor of type sec_attr_cursor_t with all resources released. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_attr_cursor_release() routine releases all resources allocated to a sec_attr_cursor_t by the sec_rgy_attr_cursor_init() or sec_rgy_attr_cursor_alloc() call. This is a local-only operation and makes not remote calls. Permissions Required None. ERRORS No such object error_status_ok RELATED INFORMATION Functions: sec_intro sec_rgy_attr_cursor_init sec_rgy_attr_cursor_alloc sec_rgy_attr_lookup_by_id 4 sec_rgy_attr_cursor_reset NAME sec_rgy_attr_cursor_reset - Rinitializes a cursor that has been allocated with either sec_rgy_attr_cursor_init() or sec_rgy_attr_cursor_alloc(). SYNOPSIS #include void sec_attr_cursor_reset( sec_attr_cursor_t *cursor, error_status_t *status); PARAMETERS Input/Output cursor A pointer to a sec_attr_cursor_t. As an input parameter, an initialized cursor. As an output parameter, cursor is reset to the first attribute in the schema. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_attr_cursor_reset() routine resets a dce_attr_cursor_t that has been allocated by either a sec_rgy_attr_cursor_init() or sec_rgy_attr_cursor_alloc(). The reset cursor can then be used to process a new sec_rgy_attr_lookup_by_id query by reusing the cursor instead of releasing and re-allocating it. This is a local operation and makes no remote calls. Permissions Required None. FILES SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR.IDL The idl file from which dce/sec_rgy_attr.h was derived. ERRORS error_status_ok RELATED INFORMATION Functions: sec_intro sec_rgy_attr_cursor_init sec_rgy_attr_cursor_alloc sec_rgy_attr_lookup_by_id 4 sec_rgy_attr_delete NAME sec_rgy_attr_delete - Deletes specified attributes for a specified object SYNOPSIS #include void sec_rgy_attr_delete ( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, sec_rgy_name_t name, unsigned32 num_to_delete, sec_attr_t attrs[], signed32 *failure_index, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain A value of type sec_rgy_domain_t that identifies the registry domain in which the object identified by name resides. The valid values are as follows: sec_rgy_domain_person The name identifies a principal. sec_rgy_domain_group The name identifies a group. sec_rgy_domain_org The name identifies an organization. This parameter is ignored if name is policy or replist. name A character string of type sec_rgy_name_t specifying the name of the person, group, or organization to which the attributes are attached. num_to_delete A 32-bit integer that specifies the number of elements in the attrs[] array. This integer must be greater than 0. attrs[] An array of values of type sec_attr_t that specifies the attribute instances to be deleted. The size of the array is determined by num_to_delete. Output failure_index In the event of an error, failure_index is a pointer to the element in the in_attrs[] array that caused the update to fail. If the failure cannot be attributed to a specific attribute, the value of failure_index is -1. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_attr_delete() routine deletes attributes. This is an atomic operation: if the deletion of any attribute in the attrs[] array fails, all deletions are aborted. The attribute causing the delete to fail is identified in failure_index. If the failure cannot be attributed to a given attribute, failure_index contains -1. The attrs array, which specifies the attributes to be deleted, contains values of type sec_attr_t These values consist of: + attr_id, a UUID that identifies the attribute type + attr_value, values of sec_attr_value_t that specify the attribute's encoding type and values. To delete attributes that are not multi-valued and to delete all instances of a multi-valued attribute, an attribute UUID is all that is required. For these attribute instances, supply the attribute UUID in the input array and set the attribute encoding (in sec_attr_encoding_t) to sec_attr_enc_void. To delete a specific instance of a multi-valued attribute, supply the UUID and value that uniquely identify the multi-valued attribute instance in the input array. Note that if the deletion of any attribute instance in the array fails, all fail. However, to help pinpoint the cause of the failure, the call identifies the first attribute whose deletion failed in a failure index by array element number. Permissions Required The sec_rgy_attr_delete() routine requires the delete permission set for each attribute type identified in the attrs[] array. These permissions are defined as part of the ACL manager set in the schema entry for the attribute type. FILES SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR.IDL The idl file from which dce/sec_rgy_attr.h was derived. ERRORS unauthorized database read only server unavailable invalid/unsupported attribute type site read only error_status_ok RELATED INFORMATION Functions: sec_intro sec_rgy_attr_update 4 sec_rgy_attr_get_effective NAME sec_rgy_attr_get_effective - Reads effective attributes by ID SYNOPSIS #include void sec_rgy_attr_get_effective( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, sec_rgy_name_t name, unsigned32 num_attr_keys, sec_attr_t attr_keys[], sec_attr_vec_t *attr_list, error_status_t status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain A value of type sec_rgy_domain_t that identifies the domain in which the named object resides. The valid values are as follows: sec_rgy_domain_principal The name identifies a principal. sec_rgy_domain_group The name identifies a group. sec_rgy_domain_org The name identifies an organization. This parameter is ignored if name is policy or replist. name A pointer to a sec_rgy_name_t character string containing the name of the person, group, or organization to which the attribute is attached. num_attr_keys An unsigned 32-bit integer that specifies the number of elements in the the attr_keys[] array. If num_attr_keys is set to 0, all of the effective attributes that the caller is authorized to see are returned. attr_keys[] An array of values of type sec_attr_t that specify the UUIDs of the attributes to be returned if they are effective. If the attribute type is associated with a query attribute trigger, the sec_attr_t attr_value field can be used to pass in optional information required by the attribute trigger query. If no information is to be passed in the attr_value field (whether the type indicates an attribute trigger query or not), set the attribute's encoding type to sec_rgy_attr_enc_void. The size of the attr_keys[] array is determined by the num_attr_keys parameter. Output attr_list A pointer an attribute vector allocated by the server containing all of the effective attributes matching the search criteria (defined in num_attr_keys or attr_keys[] ). The server allocates a buffer large enough to return all the requested attributes so that subsequent calls are not necessary. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_attr_get_effective() routine returns the UUIDs of a pecified object's effective attributes. Effective attributes are determined by setting of the schema entry apply_defaults flag: + If the flag is set off, only the attributes directly attached to the object are effective. + If the flag is set on, the effective attributes are obtained by performing the following steps for each attribute identified by UUID in the attr_keys array: 1. If the object named by name is a principal and if the a requested attribute exists on the principal, that attribute is effective and is returned. If it does not exist, the search continues. 2. The next step in the search depends on the type of object: For principals with accounts: a. The organization named in the principal's account is examined to see if an attribute of the requested type exists. If it does, it is effective and is returned; then the search for that attribute ends. If it does not exist, the search for that attribute continues to the policy object as described in b, below. b. The registry policy object is examined to see if an attribute of the requested type exits. If it does, it is returned. If it does not, a message indicating the no attribute of the type exists for the object is returned. For principals without accounts, for groups, and for organizations: the registry policy object is examined to see if an attribute of the requested type exits. If it does, it is returned. If it does not, a message indicating the no attribute of the type exists for the object is returned. For multi-valued attributes, the call returns a sec_attr_t for each value as an individual attribute instance. For attribute sets, the call returns a sec_attr_t for each member of the set; it does not return the set instance. If the attribute instance to be read is associated with a query attribute trigger that requires additional information before it can process the query request, use a sec_attr_value_t to supply the requested information. To do this: + Set the sec_attr_encoding_t to an encoding type that is compatible with the information required by the query attribute trigger. + Set the sec_attr_value_t to hold the required information. If the attribute instance to be read is not associated with a query trigger or no additional information is required by the query trigger, an attribute UUID is all that is required. For these attribute instances, supply the attribute UUID in the input array and set the attribute encoding (in sec_attr_encoding_t) to sec_attr_enc_void. If the requested attribute type is associated with a query trigger, the value returned for the attribute will be the binding (as set in the schema entry) of the trigger server. The caller must bind to the trigger server and pass the original input query attribute to the sec_attr_trig_query call in order to retrieve the attribute value. FILES SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR.IDL The idl file from which dce/sec_rgy_attr.h was derived. ERRORS error_status_ok RELATED INFORMATION Functions: sec_intro 4 sec_rgy_attr_lookup_by_id NAME sec_rgy_attr_lookup_by_id - Reads a specified object's attribute(s), expanding attribute sets into individual member attributes SYNOPSIS #include void sec_rgy_attr_lookup_by_id ( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, sec_rgy_name_t name, sec_attr_cursor_t *cursor, unsigned32 num_attr_keys, unsigned32 space_avail, sec_attr_t attr_keys[], unsigned32 *num_returned, sec_attr_t attrs[], unsigned32 *num_left, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain A value of type sec_rgy_domain_t that identifies the registry domain in which the object specified by name resides. The valid values are as follows: sec_rgy_domain_person The name identifies a principal. sec_rgy_domain_group The name identifies a group. sec_rgy_domain_org The name identifies an organization. This parameter is ignored if name is policy or replist. name A pointer to a sec_rgy_name_t character string containing the name of the person, group, or organization to which the attribute is attached. num_attr_keys An unsigned 32-bit integer that specifies the number of elements in the attr_keys array. Set this parameter to 0 to return all of the object's attributes that the caller is authorized to see. space_avail An unsigned 32-bit integer that specifies the size of the attr_keys array. attr_keys[] An array of values of type sec_attr_t that identify the attribute type ID of the attribute instance(s) to be looked up. If the attribute type is associated with a query attribute trigger, the sec_attr_t attr_value field can be used to pass in optional information required by the attribute trigger query. If no information is to be passed in the attr_value field (whether the type indicates an attribute trigger query or not), set the attribute's encoding type to sec_rgy_attr_enc_void. The size of the attr_keys[] array is determined by the num_attr_keys parameter. Input/Output cursor A pointer to a sec_attr_cursor_t. As an input parameter, cursor is a pointer to a sec_attr_cursor_t initialized by a sec_rgy_attr_srch_cursor_init call. As an output parameter, cursor is a pointer to a sec_attr_cursor_t that is positioned past components returned in this call. Output num_returned A pointer to a 32-bit unsigned integer that specifies the number of attribute instances returned in the attrs[] array. attrs An array of values of type sec_attr_t that contains the attributes retrieved by UUID. The size of the array is determined by space_avail and the length by num_returned. num_left A pointer to a 32-bit unsigned integer that supplies the number of attributes that were found but could not be returned because of space constraints in the attrs[] buffer. To ensure that all the attributes will be returned, increase the size of the attrs[] array by increasing the size of space_avail and num_returned. status A pointer to the completion status. On successful completion, the routine returns error_status_ok, or, if the requested attributes were not available, it returns the message not_all_available. Otherwise, it returns an error. DESCRIPTION The sec_rgy_attr_lookup_by_id() function reads those attributes specified by UUID for an object specified by name. This routine is similar to the sec_rgy_attr_lookup_no_expand routine with one exception: for attribute sets, the sec_rgy_attr_lookup_no_expand routine returns a sec_attr_t for the set instance only; it does not expand the set and return a sec_attr_t for each member in the set. This call expands attribute sets and returns a sec_attr_t for each member in the set. If the num_attr_keys parameter is set to 0, all of the object's attributes that the caller is authorized to see are returned. This routine is useful for programmatic access. For multi-valued attributes, the call returns a sec_attr_t for each value as an individual attribute instance. For attribute sets, the call returns a sec_attr_t for each member of the set; it does not return the set instance. The attr_keys[] array, which specifies the attributes to be returned, contains values of type sec_attr_t. These values consist of: + attr_id, a UUID that identifies the attribute type + attr_value, values of sec_attr_value_t that specify the attribute's encoding type and values. Use the attr_id field of each attr_keys array element, to specify the UUID that identifies the attribute type to be returned. If the attribute instance to be read is not associated with a query trigger or no additional information is required by the query trigger, an attribute UUID is all that is required. For these attribute instances, supply the attribute UUID in the input array and set the attribute encoding (in sec_attr_encoding_t) to sec_attr_enc_void. If the attribute instance to be read is associated with a query attribute trigger that requires additional information before it can process the query request, use a sec_attr_value_t to supply the requested information. To do this: + Set the sec_attr_encoding_t to an encoding type that is compatible with the information required by the query attribute trigger. + Set the sec_attr_value_t to hold the required information. Note that if you set num_attr_keys to zero to return all of the object's attributes and that attribute is associated with a query attribute trigger, the attribute trigger will be called with no input attribute information (that would normally have been passed in via the attr_value field). The cursor parameter specifies a cursor of type sec_attr_cursor_t initialized to the point in the attribute list at which to start processing the query. Use the sec_attr_cursor_init function to initialize cursor. If cursor is uninitialized, the server begins processing the query at the first attribute that satisfies the search criteria. The num_left parameter contains the number of attributes that were found but could not be returned because of space constraints of the attrs[] array. (Note that this number may be inaccurate if the target server allows updates between successive queries.) To obtain all of the remaining attributes, set the size of the attrs[] array so that it is large enough to hold the number of attributes listed in num_left. Permissions Required The sec_rgy_attr_lookup_by_id() routine requires the query permission set for each attribute type identified in the attr_keys[] array. These permissions are defined as part of the ACL manager set in the schema entry of each attribute type. FILES SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR.IDL The idl file from which dce/sec_rgy_attr.h was derived. ERRORS unauthorized registry server unavailable trigger server unavailable error_status_ok RELATED INFORMATION Functions: sec_intro sec_rgy_attr_lookup_no_expand sec_rgy_attr_attr_lookup_by_name 4 sec_rgy_attr_lookup_by_name NAME sec_rgy_attr_lookup_by_name - Read a single attribute instance for a specific object SYNOPSIS #include void sec_rgy_attr_lookup_by_name( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, sec_rgy_name_t name, char *attr_name, sec_attr_t *attr, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain A value of type sec_rgy_domain_t that identifies the domain in which the named object resides. The valid values are as follows: sec_rgy_domain_principal The name identifies a principal. sec_rgy_domain_group The name identifies a group. sec_rgy_domain_org The name identifies an organization. This parameter is ignored if name is policy or replist. name A pointer to a sec_rgy_name_t character string containing the name of the person, group, or organization to which the attribute is attached. attr_name An pointer to a character string that specifies the name of the attribute to be retrieved. Output attr A pointer to a sec_attr_t that contains the first instance of the named attribute. status A pointer to the completion status. The completion status can be one of the following: + error_status_ok if all instances of the value are returned with no errors. + more_available if a multi-valued attribute was specified as name and the routine completed successfully. For multi- valued attributes, this routine returns the first instance of the attribute. + attribute_set_instance if an attribute set was specified as name and the routine completed successfully. + An error message is the routine did not complete successfully. DESCRIPTION The sec_rgy_attr_lookup_by_name() routine returns the named attribute for a named object. This routine is useful for an interactive editor. For multi-valued attributes, this routine returns the first instance of the attribute. To retrieve every instance of the attribute, use the sec_rgy_attr_lookup_by_id call, supplying the attribute UUID returned in the attr parameter. For attribute sets, the routine returns the attribute set instance, not the member instances. To retrieve all members of the set, use the sec_rgy_attr_lookup_by_id call, supplying the the attribute set UUID returned in the attr parameter. Warning This routine does not provide for input data to an attribute trigger query operation. If the named attribute is associated with a query attribute trigger, the attribute trigger will be called with no input attribute value information. Permissions Required The sec_rgy_attr_lookup_by_name() routine requires the query permission set for the attribute type of the attribute instance identified by attr_name. These permissions are defined as part of the ACL manager set in the schema entry of each attribute type ERRORS unauthorized registry server unavailable trigger server unavailable error_status_ok RELATED INFORMATION Functions: sec_intro sec_rgy_attr_lookup_by_id sec_rgy_attr_lookup_no_expand 4 sec_rgy_attr_lookup_no_expand NAME sec_rgy_attr_lookup_no_expand - Reads a specified object's attribute(s), without expanding attribute sets into individual member attributes SYNOPSIS #include void sec_rgy_attr_lookup_no_expand( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, sec_rgy_name_t name, sec_attr_cursor_t *cursor, unsigned32 num_attr_keys, unsigned32 space_avail, uuid_t attr_keys[], unsigned32 *num_returned, sec_attr_t attr_sets[], unsigned32 *num_left, error_status_t status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain A value of type sec_rgy_domain_t that identifies the domain in which the named object resides. The valid values are as follows: sec_rgy_domain_principal The name identifies a principal. sec_rgy_domain_group The name identifies a group. sec_rgy_domain_org The name identifies an organization. This parameter is ignored if name is policy or replist. name A pointer to a sec_rgy_name_t character string containing the name of the person, group, or organization to which the attribute is attached. num_attr_keys An unsigned 32-bit integer that specifies the number of elements in the the attr_keys[] array. If num_attr_keys is set to 0, all attribute sets that the caller is authorized to see are returned. space_avail An unsigned 32-bit integer that specifies the size of the attrs_sets[] array. attr_keys[] An array of values of type uuid_t that specify the UUIDs of the attribute sets to be returned. The size of the attr_keys[] array is determined by the num_attr_keys parameter. Input/Output cursor A pointer to a sec_attr_cursor_t. As an input parameter, cursor is a pointer to a sec_attr_cursor_t that is initialized by the sec_rgy_attr_cursor_init. As an output parameter, cursor is a pointer to a sec_attr_cursor_t that is positioned past the attribute sets returned in this call. Output num_returned A pointer to a 32-bit integer that specifies the number of attribute sets returned in the attrs[] array. attr_sets An array of values of type sec_attr_t that contains the attribute sets retrieved by UUID. The size of the array is determined by space_avail and the length by num_returned. num_left A pointer to a 32-bit unsigned integer that supplies the number of attribute sets that were found but could not be returned because of space constraints in the attr_sets[] buffer. To ensure that all the attributes will be returned, increase the size of the attr_sets[] array by increasing the size of space_avail and num_returned. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_attr_lookup_no_expand() routine reads attribute sets. This routine is similar to the sec_rgy_attr_lookup_by_id() routine with one exception: for attribute sets, the sec_rgy_attr_lookup_by_id() routine expands attribute sets and returns a sec_attr_t for each member in the set. This call does not. Instead it returns a sec_attr_t for the set instance only. The sec_rgy_attr_lookup_no_expand() routine is useful for programmatic access. cursor is a cursor of type sec_attr_cursor_t that establishes the point in the attribute set list from which the server should start processing the query. Use the sec_rgy_attr_cursor_init function to initialize cursor. If cursor is uninitialized, the server begins processing the query with the first attribute that satisfies the search criteria. The num_left parameter contains the number of attribute sets that were found but could not be returned because of space constraints of the attr_sets[] array. (Note that this number may be inaccurate if the target server allows updates between successive queries.) To obtain all of the remaining attribute sets, set the size of the attr_sets[] array so that it is large enough to hold the number of attributes listed in num_left. Permissions Required The sec_rgy_attr_lookup_no_expand() routine requires the query permission set for each attribute type identified in the attr_keys[] array. These permissions are defined as part of the ACL manager set in the schema entry of each attribute type. FILES SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR.IDL The idl file from which dce/sec_rgy_attr.h was derived. ERRORS unauthorized registry server unavailable invalid/unsupported attribute type error_status_ok RELATED INFORMATION Functions: sec_intro sec_rgy_attr_lookup_by_id sec_rgy_attr_lookup_by_name 4 sec_rgy_attr_sch_aclmgr_strings NAME sec_rgy_attr_sch_aclmgr_strings - Returns printable ACL strings associated with an ACL manager protecting a bound to schema object SYNOPSIS #include void sec_rgy_attr_sch_aclmgr_strings( sec_rgy_handle_t context, sec_attr_component_name_t schema_name, uuid_t *acl_mgr_type, unsigned32 size_avail, uid_t *acl_mgr_type_chain, sec_acl_printstring_t *acl_mgr_info, boolean32 *tokenize, unsigned32 *total_num_printstrings, unsigned32 *size_used, sec_acl_printstring_t permstrings[], error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open to acquire a bound handle. schema_name Reserved for future use. acl_manager_type A pointer to the UUID identifying the type of the ACL manager in question. There may be more than one type of ACL manager protecting the schema object whose ACL is bound to the input handle. Use this parameter to distinguish them. Use sec_rgy_attr_sch_get_acl_mgrs to acquire a list of the manager types protecting a given schema object. size_avail An unsigned 32-bit integer containing the allocated length of the permstrings[] array. Output acl_mgr_type_chain If the target object ACL contains more than 32 permission bits, chains of manager types are used: each manager type holds one 32-bit segment of permissions. The UUID returned in acl_mgr_type_chain refers to the next ACL manager in the chain. If there are no more ACL managers in the chain, uuid_nil is returned. acl_mgr_info A pointer to a printstring that contains the ACL manager type's name, help information, and set of supported of permission bits. tokenize A pointer to a variable that specifies whether or not printstrings will be passed separately: + TRUE indicates that the printstrings must be printed or passed separately. + FALSE indicates that the printstrings are unambiguous and can be concatenated when printed without confusion. total_num_printstrings A pointer to an unsigned 32-bit integer containing the total number of permission entries supported by this ACL manager type. size_used A pointer to an unsigned 32-bit integer containing the number of permission entries returned in the permstrings[] array. permstrings[] An array of printstrings of type sec_acl_printstring_t. Each entry of the array is a structure containing the following three components: printstring A character string of maximum length sec_acl_printstring_len describing the printable representation of a specified permission. helpstring A character string of maximum length sec_acl_printstring_help_len containing some text that can be used to describe the specified permission. permissions A sec_acl_permset_t permission set describing the permissions that are represented with the companion printstring. The array consists of one such entry for each permission supported by the ACL manager identified by acl_mgr_type. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_attr_sch_aclmgr_strings() routine returns an array of printable representations (called "printstrings") for each permission bit or combination of permission bits the specified ACL manager supports. The ACL manager type specified by acl_mgr_type must be one of the types protecting the schema object bound to by h. In addition to returning the printstrings, this routine also returns instructions about how to print the strings in the tokenize variable. If this variable is set to FALSE, the printstrings can be concatenated. If it is set to TRUE, the printstrings cannot be concatenated. For example a printstrings of r or w could be concatenated as rw without any confusion. However, printstrings in a form of read or write, should not be concatenated. ACL managers often define aliases for common permission combinations. By convention, simple entries appear at the beginning of the printstrings[] array, and combinations appear at the end. Permissions Required The sec_rgy_attr_sch_scl_mgr_strings() routine requires the r permission on the attr_schema object. FILES SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL The idl file from which dce/sec_rgy_attr_sch.h was derived. ERRORS sec_attr_unauthorized sec_attr_svr_unavailable sec_attr_no_memory error_status_ok RELATED INFORMATION Functions: sec_intro sec_rgy_attr_sch_get_acl_mgrs 4 sec_rgy_attr_sch_create_entry NAME sec_rgy_attr_sch_create_entry - Create a schema entry SYNOPSIS #include void sec_rgy_attr_sch_create_entry( sec_rgy_handle_t context, sec_attr_component_name_t schema_name, sec_attr_schema_entry_t *schema_entry, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open to acquire a bound handle. schema_name Reserved for future use. schema_entry A pointer to a sec_attr_schema_entry_t that contains the schema entry values for the schema in which the entry is to be created. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_attr_sch_create_entry() routine creates schema entries that define attribute types. Permissions Required The sec_rgy_attr_sch_create_entry() routine requires i permission on the attr_schema object. FILES SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL The idl file from which dce/sec_rgy_attr_sch.h was derived. ERRORS sec_attr_bad_name sec_attr_bad_encoding_type sec_attr_bad_acl_mgr_set sec_attr_bad_acl_mgr_type sec_attr_bad_permset sec_attr_bad_intercell_action sec_attr_trig_bind_info_missing sec_attr_bad_bind_info sec_attr_bad_bind_svr_name sec_attr_bad_bind_prot_level sec_attr_bad_bind_authn_svc sec_attr_bad_bind_authz_svc sec_attr_bad_uniq_query_accept sec_attr_bad_scope sec_attr_bad_comment sec_attr_type_id_exists sec_attr_name_exists sec_attr_unauthorized sec_attr_svr_read_only sec_attr_svr_unavailable sec_attr_no_memory RELATED INFORMATION Functions: sec_intro sec_rgy_attr_sch_delete_entry sec_rgy_attr_sch_update 4 sec_rgy_attr_sch_cursor_alloc NAME sec_rgy_attr_sch_cursor_alloc - Allocates resources to a cursor used with the sec_rgy_attr_sch_scan call SYNOPSIS void sec_rgy_att_sch_cursor_alloc( dce_attr_cursor_t *cursor, error_status_t *status); PARAMETERS Output cursor A pointer to a sec_attr_cursor_t. status A pointer to the completion status. On successful completion, the call returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_attr_sch_cursor_alloc() call allocates resources to a cursor used with the sec_rgy_attr_sch_scan() call. This routine, which is a local operation, does not initialize cursor. The sec_rgy_attr_sch_cursor_init() routine, which makes a remote call, allocates and initializes the cursor. In addition, sec_rgy_attr_sch_cursor_init() returns the total number of entries found in the schema as an output parameter; sec_rgy_attr_sch_cursor_alloc() does not. Permissions Required None. FILES SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL The idl file from which dce/sec_rgy_attr_sch.id was derived. ERRORS sec_attr_no_memory error_status_ok RELATED INFORMATION Functions: sec_intro sec_rgy_attr_sch_cursor_init sec_rgy_attr_sch_cursor_release sec_rgy_attr_sch_scan 4 sec_rgy_attr_sch_cursor_init NAME sec_rgy_attr_sch_cursor_init - Initialize and allocate a cursor used with the sec_rgy_attr_sch_scan call SYNOPSIS #include void sec_rgy_attr_cursor_init( sec_rgy_handle_t context, sec_attr_component_name_t schema_name, unsigned32 *cur_num_entries, sec_attr_cursor_t *cursor, error_status_t status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. schema_name Reserved for future use. Output cur_num_entries A pointer to an unsigned 32-bit integer that specifies the total number of entries contained in the schema at the time of this call. cursor A pointer to a sec_attr_cursor_t that is initialized to the first entry in the the schema. status A pointer to the completion status. On successful completion, the call returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_attr_sch_cursor_init() call initializes and allocates resources to a cursor used with the sec_rgy_attr_sch_scan call. This call makes remote calls to initialize the cursor. To limit the number of remote calls, use the sec_rgy_attr_sch_cursor_alloc() call to allocate cursor, but not initialize it. Be aware, however, that the sec_rgy_attr_sch_cursor_init() call supplies the total number of entries found in the schema as an output parameter; the sec_rgy_attr_sch_cursor_alloc() call does not. If the cursor iunput to sec_rgy_attr_sch_scan has not been initialized, the sec_rgy_attr_sch_scan call will initialize it; if it has been initialized, sec_rgy_attr_sch_scan advances it. Permissions Required None. FILES SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL The idl file from which dce/sec_rgy_attr_sch.h was derived. ERRORS sec_attr_unauthorized sec_attr_svr_unavailable sec_attr_no_memory error_status_ok RELATED INFORMATION Functions: sec_intro sec_rgy_attr_sch_cursor_release sec_rgy_attr_sch_scan sec_rgy_attr_sch_cursor_alloc 4 sec_rgy_attr_sch_cursor_release NAME sec_rgy_attr_sch_cursor_release - Release states associated with a cursor used by the sec_rgy_attr_sch_scan routine SYNOPSIS #include void sec_rgy_attr_cursor_release( sec_attr_cursor_t *cursor, error_status_t *status); PARAMETERS Input/Output cursor A pointer to a sec_attr_cursor_t. As an input parameter, cursor must have been initialized to the first entry in a schema. As an output parameter, cursor is uninitialized with all resources releases. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_attr_sch_cursor_init() routine releases the resources allocated to the cursor used by the sec_rgy_attr_sch_scan routine. This call is a local operation and makes no remote calls. Permissions Required None. FILES SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL The idl file from which dce/sec_rgy_attr_sch.h was derived. ERRORS error_status_ok RELATED INFORMATION Functions: sec_intro sec_rgy_attr_sch_cursor_init sec_rgy_attr_sch_cursor_allocate sec_rgy_attr_sch_scan 4 sec_rgy_attr_sch_cursor_reset NAME sec_rgy_attr_sch_cursor_reset - Resets a cursor that has been allocated with either sec_rgy_attr_sch_cursor_init() or sec_rgy_attr_sch_cursor_alloc(). SYNOPSIS #include void dce_attr_cursor_reset( sec_attr_cursor_t *cursor, error_status_t *status); PARAMETERS Input/Output cursor A pointer to a sec_attr_cursor_t. As an input parameter, an initialized cursor. As an output parameter, cursor is reset to the first attribute in the schema. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_attr_sch_cursor_reset() routine resets a dce_attr_cursor_t that has been allocated by either a sec_rgy_attr_sch_cursor_init() or sec_rgy_attr_sch_cursor_alloc(). The reset cursor can then be used to process a new sec_rgy_attr_sch_scan query by reusing the cursor instead of releasing and re-allocating it. This is a local operation and makes no remote calls. Permissions Required None. FILES SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL The idl file from which dce/sec_rgy_attr_sch.h was derived. ERRORS sec_attr_bad_cursor error_status_ok RELATED INFORMATION Functions: sec_intro sec_rgy_attr_sch_cursor_init sec_rgy_attr_sch_cursor_alloc sec_rgy_attr_sch_scan 4 sec_rgy_attr_sch_delete_entry NAME sec_rgy_attr_sch_delete_entry - Delete a schema entry SYNOPSIS #include void sec_rgy_attr_sch_delete_entry( sec_rgy_handle_t context, sec_attr_component_name_t schema_name, uuid_t *attr_id, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. schema_name Reserved for future use. attr_id A pointer to a uuid_t that identifies the schema entry to be deleted. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_attr_sch_delete_entry() routine deletes a schema entry. Because this is a radical operation that invalidates any existing attributes of this type on objects dominated by the schema, access to this operation should be severely limited. Permissions Required The sec_rgy_attr_sch_delete_entry() routine requires the d permission on the attr_schema object. FILES SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL The idl file from which dce/sec_rgy_attr_sch.h was derived. ERRORS sec_attr_sch_entry_not_found sec_attr_unauthorized sec_attr_svr_read_only sec_attr_svr_unavailable sec_attr_no_memory error_status_ok RELATED INFORMATION Functions: sec_intro sec_rgy_attr_sch_create_entry sec_rgy_attr_sch_update_entry 4 sec_rgy_attr_sch_get_acl_mgrs NAME sec_rgy_attr_sch_get_acl_mgrs - Retrieve the manager types of the ACLs protecting the objects dominated by a named schema SYNOPSIS #include void sec_rgy_attr_sch_get_acl_mgrs( sec_rgy_handle_t context, sec_attr_component_name_t schema_name, unsigned32 size_avail, unsigned32 *size_used, unsigned32 *num_acl_mgr_types, uuid_t acl_mgr_types[], error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. schema_name Reserved for future use. size_avail An unsigned 32-bit integer containing the allocated length of the acl_manager_types[] array. Output size_used An unsigned 32-bit integer containing the number of output entries returned in the acl_mgr_types[] array. num_acl_mgr_types An unsigned 32-bit integer containing the number of types returned in the acl_mgr_types[] array. This may be greater than size_used if there was not enough space allocated by size_avail for all the manager types in the acl_manager_types[] array. acl_mgr_types[] An array of the length specified in size_avail to contain UUIDs (of type uuid_t) identifying the types of ACL managers protecting the target object. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_attr_sch_get_acl_mgrs() routine returns a list of the manager types protecting the schema object identified by context. ACL editors and browsers can use this operation to determine the ACL manager types protecting a selected schema object. Then, using the sec_rgy_attr_sch_aclmgr_strings() routine, they can determine how to format for display the permissions supported by that ACL manager type. Permissions Required The sec_rgy_attr_sch_get_acl_mgrs() routine requires the r permission on the attr_schema object. FILES SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL The idl file from which dce/sec_rgy_attr_sch.h was derived. ERRORS sec_attr_unauthorized sec_attr_svr_unavailable sec_attr_no_memory error_status_ok RELATED INFORMATION Functions: sec_intro sec_rgy_attr_sch_aclmgr_strings 4 sec_rgy_attr_sch_lookup_by_id NAME sec_rgy_attr_sch_lookup_by_id - Read a schema entry identified by UUID SYNOPSIS #include void sec_rgy_attr_sch_lookup_by_id( sec_rgy_handle_t context, sec_attr_component_name_t schema_name, uuid_t *attr_id, sec_attr_schema_entry_t *schema_entry, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. schema_name Reserved for future use. attr_id A pointer to a uuid_t that identifies a schema entry. Output schema_entry A sec_attr_schema_entry_t that contains an entry identified by attr_id. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_attr_sch_lookup_by_id() routine reads a schema entry identified by attr_id. This routine is useful for programmatic access. Permissions Required The sec_rgy_attr_sch_lookup_by_id() routine requires the r permission on the attr_schema object. FILES SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL The idl file from which dce/sec_rgy_attr_sch.h was derived. ERRORS sec_attr_sch_entry_not_found sec_attr_unauthorized sec_attr_svr_unavailable sec_attr_no_memory error_status_ok RELATED INFORMATION Functions: sec_intro sec_rgy_attr_sch_lookup_by_name sec_rgy_attr_sch_scan 4 sec_rgy_attr_sch_lookup_by_name NAME sec_rgy_attr_sch_lookup_by_name - Read a schema entry identified by name SYNOPSIS #include void sec_rgy_attr_sch_lookup_by_name( sec_rgy_handle_t context, sec_attr_component_name_t schema_name, char *attr_name, sec_attr_schema_entry_t *schema_entry, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. schema_name Reserved for future use. attr_name A pointer to a character string that identifies the schema entry. Output schema_entry A sec_attr_schema_entry_t that contains the schema entry identified by attr_name. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_attr_sch_lookup_by_name() routine reads a schema entry identified by name. This routine is useful for use with an interactive editor. Permissions Required The sec_rgy_attr_sch_lookup_by_name() routine requires the r permission on the attr_schema object. FILES SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL The idl file from which dce/sec_rgy_attr_sch.h was derived. ERRORS sec_attr_sch_entry_not_found sec_attr_bad_name sec_attr_unauthorized sec_attr_svr_unavailable sec_attr_no_memory error_status_ok RELATED INFORMATION Functions: sec_intro sec_rgy_attr_sch_lookup_by_id sec_rgy_attr_sch_scan 4 sec_rgy_attr_sch_scan NAME sec_rgy_attr_sch_scan - Read a specified number of schema entries SYNOPSIS #include void sec_rgy_attr_sch_scan( sec_rgy_handle_t context, sec_attr_component_name_t schema_name, sec_attr_cursor_t *cursor, unsigned32 num_to_read, unsigned32 *num_read, sec_attr_schema_entry_t schema_entries[], error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. schema_name Reserved for future use. num_to_read An unsigned 32-bit integer specifying the size of the schema_entries[] array and the maximum number of entries to be returned. Input/Output cursor A pointer to a sec_attr_cursor_t. As input cursor must be allocated and can be initialized. If cursor is not initialized, sec_rgy_attr_sch_scan will initialized. As output, cursor is positioned at the first schema entry after the returned entries. Output num_read A pointer an unsigned 32-bit integer specifying the number of entries returned in schema_entries[]. schema_entries[] A sec_attr_schema_entry_t that contains an array of the returned schema entries. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_attr_sch_scan() routine reads schema entries. The read begins at the entry at which the input cursor is positioned and ends after the number of entries specified in num_to_read. The input cursor must have been allocated by either the sec_rgy_attr_sch_cursor_init() or the sec_rgy_attr_sch_cursor_alloc() call. If the input cursor is not initialzed, sec_rgy_attr_sch_scan() initializes it; if cursor is initialized, sec_rgy_attr_sch_scan() simply advances it. To read all entries in a schema, make successive sec_rgy_attr_sch_scan() calls. When all entries have been read, the call returns the message no_more_entries. This routine is useful as a browser. Permissions Required The sec_rgy_attr_sch_scan() routine requires r permission on the attr_schema object. FILES SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL The idl file from which dce/sec_rgy_attr_sch.h was derived. ERRORS sec_attr_bad_cursor sec_attr_unauthorized sec_attr_svr_unavailable sec_attr_no_memory error_status_ok RELATED INFORMATION Functions: sec_intro sec_rgy_attr_sch_cursor_init sec_rgy_attr_sch_cursor_alloc sec_rgy_attr_sch_cursor_release 4 sec_rgy_attr_sch_update_entry NAME sec_rgy_attr_sch_update_entry - Update a schema entry SYNOPSIS #include void sec_rgy_attr_sch_update_entry( sec_rgy_handle_t context, sec_attr_component_name_t schema_name, sec_attr_schema_entry_parts_t modify_parts, sec_attr_schema_entry_t *schema_entry, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. schema_name Reserved for future use. modify_parts A value of type sec_attr_schema_entry_parts_t that identifies the fields in schema_entry that can be modified. schema_entry A pointer to a sec_attr_schema_entry_t that contains the schema entry values for the schema entry to be updated. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_attr_sch_update_entry() routine modifies schema entries. Only those schema entry fields set to be modified in the sec_attr_schema_entry_parts_t data type can be modified. Some schema entry components can never be modified. Instead to make any changes to these components, the schema entry must be deleted (which deletes all attribute instances of that type) and recreated. The schema entry components that can never be modified are listed below: + Attribute name + Reserved flag + Apply defaults flag + Intercell action flag + Trigger binding + Comment Fields that are arrays of structures (such as acl_mgr_set and trig_binding) are completely replaced by the new input array. This operation cannot be used to add a new element to the existing array. Permissions Required The sec_rgy_attr_sch_update_entry() routine requires the M permission on the attr_schema object. FILES SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR_SCH.IDL The idl file from which dce/sec_rgy_attr_sch.h was derived. ERRORS sec_attr_field_no_update sec_attr_bad_name sec_attr_bad_acl_mgr_set sec_attr_bad_acl_mgr_type sec_attr_bad_permset sec_attr_bad_intercell_action sec_attr_trig_bind_info_missing sec_attr_bad_bind_info sec_attr_bad_bind_svr_name sec_attr_bad_bind_prot_level sec_attr_bad_bind_authn_svc sec_attr_bad_bind_authz_svc sec_attr_bad_uniq_query_accept sec_attr_bad_comment sec_attr_name_exists sec_attr_sch_entry_not_found sec_attr_unauthorized sec_attr_svr_read_only sec_attr_svr_unavailable sec_attr_no_memory error_status_ok RELATED INFORMATION Functions: sec_intro sec_rgy_attr_sch_delete_entry sec_rgy_attr_sch_create_entry 4 sec_rgy_attr_test_and_update NAME sec_rgy_attr_test_and_update - Updates specified attribute instances for a specified object only if a set of control attribute instances match the object's existing attribute instances SYNOPSIS #include void sec_rgy_attr_test_and_update ( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, sec_rgy_name_t name, unsigned32 num_to_test, sec_attr_t test_attrs[], unsigned32 num_to_write, sec_attr_t update_attrs[], signed32 *failure_index, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain A value of type sec_rgy_domain_t that identifies the registry domain in which the object specified by name resides. The valid values are as follows: sec_rgy_domain_person The name identifies a principal. sec_rgy_domain_group The name identifies a group. sec_rgy_domain_org The name identifies an organization. This parameter is ignored if name is policy or replist. name A character string of type sec_rgy_name_t specifying the name of the person, group, or organization to which the attribute is attached. num_to_test An unsigned 32-bit integer that specifies the number of elements in the test_attrs[] array. This integer must be greater than 0. test_attrs[] An array of values of type sec_attr_t that specifies the control attributes. The update takes place only if the types and values of the control attributes exactly match those of the attribute instances on the named registry object. The size of the array is determined by num_to_test. num_to_write A 32-bit integer that specifies the number of attribute instances returned in the update_attrs[] array. update_attrs An array of values of type sec_attr_t that specifies the attribute instances to be updated. The size of the array is determined by num_to_write. Output failure_index In the event of an error, failure_index is a pointer to the element in the update_attrs[] array that caused the update to fail. If the failure cannot be attributed to a specific attribute, the value of failure_index is -1. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_attr_test_and_update() routine updates an attribute only if the set of control attributes specified in the test_attrs[] match attributes that already exist for the object. This update is an atomic operation: if any of the control attributes do not match existing attributes, none of the updates are performed, and if an update should be performed, but the write cannot occur for whatever reason to any member of the update_attrs[] array, all updates are aborted. The attribute causing the update to fail is identified in failure_index. If the failure cannot be attributed to a given attribute, failure_index contains -1. If an attribute instance already exists which is identical in both attr_id and attr_value to an attribute specified in in_attrs[], the existing attribute information is overwritten by the new information. For multi-valued attributes, every instance with the same attr_id is overwritten with the supplied values. If an attribute instance does not exist, it is created. If you specify an attribute set for updating, the update applies to the set instance, the set itself, not the members of the set. To update a member of an attribute set, supply the UUID of the set member. If an input attribute is associated with an update attribute trigger server, the attribute trigger server is invoked (by the sec_attr_trig_update() function) and the in_attr[] array is supplied as input. The output attributes from the update attribute trigger server are stored in the registry database and returned in the out_attrs[] array. Note that the update attribute trigger server may modify the values before they are used to update the registry database. This is the only circumstance under which the values in the out_attrs[] array differ from the values in the in_attrs[] array. Permissions Required The sec_rgy_attr_test_and_update() routine routine requires the test permission and the update permission set set for each attribute type identified in the test_attrs[] array. These permissions are defined as part of the ACL manager set in the schema entry of each attribute type. FILES SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR.IDL The idl file from which dce/sec_rgy_attr.h was derived. ERRORS control attribute has changed unauthorized database read only server unavailable invalid/unsupported attribute type invalid encoding type value not unique trigger server unavailable site read only error_status_ok RELATED INFORMATION Functions: sec_intro sec_rgy_attr_update sec_rgy_attr_delete 4 sec_rgy_attr_update NAME sec_rgy_attr_update - Creates and updates attribute instances for a specified object SYNOPSIS #include void sec_rgy_attr_update ( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, sec_rgy_name_t name, unsigned32 num_to_write, unsigned32 space_avail, sec_attr_t in_attrs[], unsigned32 *num_returned, sec_attr_t out_attrs[], unsigned32 *num_left, signed32 *failure_index, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain A value of type sec_rgy_domain_t that identifies the registry domain in which the object specified by name resides. The valid values are as follows: sec_rgy_domain_person The name identifies a principal. sec_rgy_domain_group The name identifies a group. sec_rgy_domain_org The name identifies an organization. This parameter is ignored if name is policy or replist. name A character string of type sec_rgy_name_t specifying the name of the person, group, or organization to which the attribute is attached. num_to_write A 32-bit unsigned integer that specifies the number of elements in the in_attrs array. This integer must be greater than 0. space_avail A 32-bit unsigned integer that specifies the size of the out_attrs array. This integer must be greater than 0. in_attrs[] An array of values of type sec_attr_t that specifies the attribute instances to be updated. The size of the array is determined by num_to_write. Output num_returned A pointer to an unsigned 32-bit integer that specifies the number of attribute instances returned in the out_attrs[] array. out_attrs An array of values of type sec_attr_t that specifies the updated attribute instances. Not that only if these attributes were processed by an update attribute trigger server will they differ from the attributes in the in_attrs[] array. The size of the array is determined by space_avail and the length by num_returned. num_left A pointer to an unsigned 32-bit integer that supplies the number of attributes that could not be returned because of space constraints in the out_attrs[] buffer. To ensure that all the attributes will be returned, increase the size of the out_attrs[] array by increasing the size of space_avail and num_returned. failure_index In the event of an error, failure_index is a pointer to the element in the in_attrs[] array that caused the update to fail. If the failure cannot be attributed to a specific attribute, the value of failure_index is -1. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_attr_update() routine creates new attribute instances and updates existing attribute instances attached to a object specified by name and Registry domain. The instances to be created or updated are passed as an array of sec_attr_t data types. This is an atomic operation: if the creation of any attribute in the in_attrs[] array fails, all updates are aborted. The attribute causing the update to fail is identified in failure_index. If the failure cannot be attributed to a given attribute, failure_index contains -1. The in_attrs array, which specifies the attributes to be created, contains values of type sec_attr_t. These values are: + attr_id, a UUID that identifies the attribute type + attr_value, values of sec_attr_value_t that specify the attribute's encoding type and values. If an attribute instance already exists which is identical in both attr_id and attr_value to an attribute specified in in_attrs, the existing attribute information is overwritten by the new information. For multi-valued attributes, every instance with the same attr_id is overwritten with the supplied values. If an attribute instance does not exist, it is created. For multi-valued attributes, because every instance of the multi-valued attribute is identified by the same UUID, every instance is overwritten with the supplied value. To change only one of the values, you must supply the values that should be unchanged as well as the new value. To create instances of multi-valued attributes, create individual sec_attr_t data types to define each multi-valued attribute instance and then pass all of them in in the input array. If an input attribute is associated with an update attribute trigger server, the attribute trigger server is invoked (by the sec_attr_trig_update() function) and the in_attr[] array is supplied as input. The output attributes from the update attribute trigger server are stored in the registry database and returned in the out_attrs[] array. Note that the update attribute trigger server may modify the values before they are used to update the registry database. This is the only circumstance under which the values in the out_attrs[] array differ from the values in the in_attrs[] array. Permissions Required The sec_rgy_attr_update() routine requires the update permission set for each attribute type identified in the in_attrs[] array. These permissions are defined as part of the ACL manager set in the schema entry of each attribute type. FILES SYS$COMMON:[DCE$LIBRARY]SEC_RGY_ATTR.IDL The idl file from which dce/sec_rgy_attr.h was derived. ERRORS unauthorized database read only server unavailable invalid/unsupported attribute type invalid encoding type value not unique attribute instance already exists trigger server unavailable site read only error_status_ok RELATED INFORMATION Functions: sec_intro sec_rgy_attr_delete sec_rgy_attr_test_and_update 4 sec_rgy_auth_plcy_get_effective NAME sec_rgy_auth_plcy_get_effective - Returns the effective authentication policy for an account SYNOPSIS #include void sec_rgy_auth_plcy_get_effective( sec_rgy_handle_t context, sec_rgy_login_name_t *account, sec_rgy_plcy_auth_t *auth_policy, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. account A pointer to the account login name (type sec_rgy_login_name_t). A login name is composed of three character strings, containing the principal, group, and organization (PGO) names corresponding to the account. If all three fields contain empty strings, the authentication policy returned is that of the registry. Output auth_policy A pointer to the sec_rgy_plcy_auth_t structure to receive the authentication policy. The authentication policy structure contains the maximum lifetime for an authentication ticket, and the maximum amount of time for which one can be renewed. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_auth_plcy_get_effective() routine returns the effective authentication policy for the specified account. The authentication policy in effect is the more restrictive of the registry and the account policies for each policy category. If no account is specified, the registry's authentication policy is returned. Permissions Required The sec_rgy_auth_plcy_get_effective() routine requires the r (read) permission on the policy object from which the data is to be returned. If an account is specified and an account policy exists, the routine also requires the r (read) permission on the account principal. FILES SYS$COMMON:[DCE$LIBRARY]POLICY.IDL The idl file from which dce/policy.h was derived. ERRORS sec_rgy_object_not_found The specified account could not be found. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_auth_plcy_get_info sec_rgy_auth_plcy_set_info 4 sec_rgy_auth_plcy_get_info NAME sec_rgy_auth_plcy_get_info - Returns the authentication policy for an account SYNOPSIS #include void sec_rgy_auth_plcy_get_info( sec_rgy_handle_t context, sec_rgy_login_name_t *account, sec_rgy_plcy_auth_t *auth_policy, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. account A pointer to the account login name (type sec_rgy_login_name_t). A login name is composed of three character strings, containing the principal, group, and organization (PGO) names corresponding to the account. Output auth_policy A pointer to the sec_rgy_plcy_auth_t structure to receive the authentication policy. The authentication policy structure contains the maximum lifetime for an authentication ticket, and the maximum amount of time for which one can be renewed. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_auth_plcy_get_info() routine returns the authentication policy for the specified account. If no account is specified, the registry's authentication policy is returned. Permissions Required The sec_rgy_auth_plcy_get_info() routine requires the r (read) permission on the policy object or account principal from which the data is to be returned. NOTES The actual policy in effect will not correspond precisely to what is returned by this call if the overriding registry authentication policy is more restrictive than the policy for the specified account. Use sec_rgy_auth_plcy_get_effective() to return the policy currently in effect for the given account. FILES SYS$COMMON:[DCE$LIBRARY]POLICY.IDL The idl file from which dce/policy.h was derived. ERRORS sec_rgy_object_not_found No account with the given login name could be found. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_auth_plcy_get_effective sec_rgy_auth_plcy_set_info 4 sec_rgy_auth_plcy_set_info NAME sec_rgy_auth_plcy_set_info - Sets the authentication policy for an account SYNOPSIS #include void sec_rgy_auth_plcy_set_info( sec_rgy_handle_t context, sec_rgy_login_name_t *account, sec_rgy_plcy_auth_t *auth_policy, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. account A pointer to the account login name (type sec_rgy_login_name_t). A login name is composed of three character strings, containing the principal, group, and organization (PGO) names corresponding to the account. All three names must be completely specified. auth_policy A pointer to the sec_rgy_plcy_auth_t structure containing the authentication policy. The authentication policy structure contains the maximum lifetime for an authentication ticket, and the maximum amount of time for which one can be renewed. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_auth_plcy_set_info() routine sets the indicated authentication policy for the specified account. If no account is specified, the authentication policy is set for the registry as a whole. Permissions Required The sec_rgy_auth_plcy_set_info() routine requires the a (auth_info) permission on the policy object or account principal for which the data is to be set. NOTES The policy set on an account may be less restrictive than the policy set for the registry as a whole. In this case, the change in policy has no effect, since the effective policy is the most restrictive combination of the principal and registry authentication policies. (See the sec_rgy_auth_plcy_get_effective() routine). FILES SYS$COMMON:[DCE$LIBRARY]POLICY.IDL The idl file from which dce/policy.h was derived. ERRORS sec_rgy_object_not_found No account with the given login name could be found. sec_rgy_not_authorized The user is not authorized to update the specified record. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_auth_plcy_get_effective sec_rgy_auth_plcy_get_info 4 sec_rgy_cell_bind NAME sec_rgy_cell_bind - Binds to a registry in a cell SYNOPSIS #include void sec_rgy_cell_bind( unsigned_char_t *cell_name, sec_rgy_bind_auth_info_t *auth_info, sec_rgy_handle_t *context, error_status_t *status); PARAMETERS Input cell_name A character string (type unsigned_char_t) containing the name of the cell in question. Upon return, a Security Server for that cell is associated with context, the registry server handle. The cell must be specified completely and precisely. This routine offers none of the pathname resolving services of sec_rgy_site_bind(). auth_info A pointer to the sec_rgy_bind_auth_info_t structure that identifies the authentication protocol, protection level, and authorization protocol to use in establishing the binding. (See the rpc_binding_set_auth_info() routine). Output context A pointer to a sec_rgy_handle_t variable. Upon return, this contains a registry server handle indicating ("bound to") the desired registry site. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_cell_bind() routine establishes a relationship with a registry site at an arbitrary level of security. The cell_name parameter identifies the target cell. FILES SYS$COMMON:[DCE$LIBRARY]BINDING.IDL The idl file from which dce/binding.h was derived. ERRORS sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_site_bind 4 sec_rgy_cursor_reset NAME sec_rgy_cursor_reset - Resets the registry database cursor SYNOPSIS #include void sec_rgy_cursor_reset( sec_rgy_cursor_t *cursor); PARAMETERS Input/Output cursor A pointer into the registry database. DESCRIPTION The sec_rgy_cursor_reset() routine resets the database cursor to return the first suitable entry. A cursor is a pointer into the registry. It serves as a place holder when returning successive items from the registry. A cursor is bound to a particular server. In other words, a cursor that is in use with one replica of the registry has no meaning for any other replica. If a calling program attempts to use a cursor from one replica with another, the cursor is reset and the routine for which the cursor was specified returns the first item in the database. A cursor that is in use with one call cannot be used with another. For example, you cannot use the same cursor on a call to sec_rgy_acct_get_projlist() and sec_rgy_pgo_get_next(). The behavior in this case is undefined. FILES SYS$COMMON:[DCE$LIBRARY]MISC.IDL The idl file from which dce/misc.h was derived. EXAMPLES The following example illustrates use of the cursor within a loop. The initial sec_rgy_cursor_reset() call resets the cursor to point to the first item in the registry. Successive calls to sec_rgy_pgo_get_next() return the next PGO item and update the cursor to reflect the last item returned. When the end of the list of PGO items is reached, the routine returns the value sec_rgy_no_more_entries in the status parameter. sec_rgy_cursor_reset(&cursor); do { sec_rgy_pgo_get_next(context, domain, scope, &cursor, &item, name &status); if (status == error_status_ok) { /* Print formatted PGO item info */ } } while (status == error_status_ok); RELATED INFORMATION Functions: sec_intro sec_rgy_acct_get_projlist sec_rgy_acct_lookup sec_rgy_pgo_get_by_id sec_rgy_pgo_get_by_name sec_rgy_pgo_get_by_unix_num sec_rgy_pgo_get_members sec_rgy_pgo_get_next 4 sec_rgy_login_get_effective NAME sec_rgy_login_get_effective - Returns the effective login data for an account SYNOPSIS #include void sec_rgy_login_get_effective( sec_rgy_handle_t context, sec_rgy_login_name_t *login_name, sec_rgy_acct_key_t *key_parts, sec_rgy_sid_t *sid, sec_rgy_unix_sid_t *unix_sid, sec_rgy_acct_user_t *user_part, sec_rgy_acct_admin_t *admin_part, sec_rgy_plcy_t *policy_data, signed32 max_number, signed32 *supplied_number, uuid_t id_projlist[], signed32 unix_projlist[], signed32 *num_projects, sec_rgy_name_t cell_name, uuid_t *cell_uuid, sec_override_fields_t *overridden, error_status_t *status); PARAMETERS Input context The registry server handle. max_number The maximum number of projects to be returned by the call. This must be no larger than the allocated size of the projlist[] arrays. Input/Output login_name A pointer to the account login name. A login name is composed of the names for the account's principal, group, and organization (PGO) items. Output key_parts A pointer to the minimum abbreviation allowed when logging in to the account. Abbreviations are not currently implemented and the only legal value is sec_rgy_acct_key_person. sid A pointer to a sec_rgy_sid_t structure to receive the returned Subject Identifier (SID) for the account. This structure consists of the UUIDs for the account's PGO items. unix_sid A pointer to a sec_rgy_unix_sid_t structure to receive the returned UNIX Subject Identifier (SID) for the account. This structure consists of the UNIX numbers for the account's PGO items. user_part A pointer to a sec_rgy_acct_user_t structure to receive the returned user data for the account. admin_part A pointer to a sec_rgy_acct_admin_t structure to receive the returned administrative data for the account. policy_data A pointer to a sec_rgy_policy_t structure to receive the policy data for the account. The policy data is associated with the account's organization, as identified in the login name. supplied_number A pointer to the actual number of projects returned. This will always be less than or equal to the max_number supplied on input. id_projlist[] An array to receive the UUID of each project returned. The size allocated for the array is given by max_number. If this value is less than the total number of projects in the account project list, multiple calls must be made to return all of the projects. unix_projlist[] An array to receive the UNIX number of each project returned. The size allocated for the array is given by max_number. If this value is less than the total number of projects in the account project list, multiple calls must be made to return all of the projects. num_projects A pointer indicating the total number of projects in the specified account's project list. cell_name The name of the account's cell. cell_uuid The UUID for the account's cell. overridden A pointer to a 32-bit set of flags identifying the local overrides, if any, for the account login information. [NOT APPLICABLE ON OPENVMS] status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_login_get_effective() routine returns effective login information for the specified account. Login information is extracted from the account's entry in the registry database. Effective login information is the login information from the registry database. The overridden parameter indicates which, if any, of the following local overrides have been defined for the account: + The UNIX user ID + The group ID + The encrypted password + The account's miscellaneous information (gecos) field + The account's home directory + The account's login shell FILES SYS$COMMON:[DCE$LIBRARY]MISC.IDL The idl file from which dce/misc.h was derived. ERRORS sec_rgy__object_not_found The specified account could not be found. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_acct_add sec_rgy_login_get_info 4 sec_rgy_login_get_info NAME sec_rgy_login_get_info - Returns login information for an account SYNOPSIS #include void sec_rgy_login_get_info( sec_rgy_handle_t context, sec_rgy_login_name_t *login_name, sec_rgy_acct_key_t *key_parts, sec_rgy_sid_t *sid, sec_rgy_unix_sid_t *unix_sid, sec_rgy_acct_user_t *user_part, sec_rgy_acct_admin_t *admin_part, sec_rgy_plcy_t *policy_data, signed32 max_number, signed32 *supplied_number, uuid_t id_projlist[], signed32 unix_projlist[], signed32 *num_projects, sec_rgy_name_t cell_name, uuid_t *cell_uuid, error_status_t *status); PARAMETERS Input context The registry server handle. max_number The maximum number of projects to be returned by the call. This must be no larger than the allocated size of the projlist[] arrays. Input/Output login_name A pointer to the account login name. A login name is composed of the names for the account's principal, group, and organization (PGO) items. Output key_parts A pointer to the minimum abbreviation allowed when logging in to the account. Abbreviations are not currently implemented and the only legal value is sec_rgy_acct_key_person. sid A pointer to a sec_rgy_sid_t structure to receive the UUID's representing the account's PGO items. unix_sid A pointer to a sec_rgy_unix_sid_t structure to receive the UNIX numbers for the account's PGO items. user_part A pointer to a sec_rgy_acct_user_t structure to receive the returned user data for the account. admin_part A pointer to a sec_rgy_acct_admin_t structure to receive the returned administrative data for the account. policy_data A pointer to a sec_rgy_policy_t structure to receive the policy data for the account. The policy data is associated with the account's organization, as identified in the login name. supplied_number A pointer to the actual number of projects returned. This will always be less than or equal to the max_number supplied on input. id_projlist[] An array to receive the UUID of each project returned. The size allocated for the array is given by max_number. If this value is less than the total number of projects in the account project list, multiple calls must be made to return all of the projects. unix_projlist[] An array to receive the UNIX number of each project returned. The size allocated for the array is given by max_number. If this value is less than the total number of projects in the account project list, multiple calls must be made to return all of the projects. num_projects A pointer indicating the total number of projects in the specified account's project list. cell_name The name of the account's cell. cell_uuid The UUID for the account's cell. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_login_get_info() routine returns login information for the specified account. This information is extracted from the account's entry in the registry database. To return any local over- rides for the account's login data, use sec_rgy_login_get_effective(). Permissions Required The sec_rgy_login_get_info() routine requires the r (read) permission on the account principal from which the data is to be returned. FILES SYS$COMMON:[DCE$LIBRARY]MISC.IDL The idl file from which dce/misc.h was derived. ERRORS sec_rgy_object_not_found The specified account could not be found. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_acct_add sec_rgy_login_get_effective 4 sec_rgy_pgo_add NAME sec_rgy_pgo_add - Adds a PGO item to the registry database SYNOPSIS #include void sec_rgy_pgo_add( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, sec_rgy_name_t name, sec_rgy_pgo_item_t *pgo_item, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain This variable identifies the type of the principal, group, or organization (PGO) item identified by the given name. The valid values are as follows: sec_rgy_domain_person The name identifies a principal. sec_rgy_domain_group The name identifies a group. sec_rgy_domain_org The name identifies an organization. name A pointer to a sec_rgy_name_t character string containing the name of the new PGO item. pgo_item A pointer to a sec_rgy_pgo_item_t structure containing the data for the new PGO item. The data in this structure includes the PGO item's name, UUID, UNIX number (if any), and administrative data, such as whether the item may have (or belong to) a concurrent group set. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_pgo_add() routine adds a PGO item to the registry database. The PGO data consists of the following: + The Universal Unique Identifier (UUID) of the PGO item. Specify NULL to have the registry server create a new UUID for an item. + The UNIX number for the PGO item. If the registry uses embedded UNIX IDs (where a subset of the UUID bits represent the UNIX ID), then the specified ID must match the UUID, if both are specified. Use a value of -1 for the UNIX number to match any value. + The quota for subaccounts allowed for this item entry. + The full name of the PGO item. + Flags (in the sec_rgy_pgo_flags_t format) indicating whether - A principal item is an alias. - The PGO item can be deleted from the registry. - A principal item can have a concurrent group set. - A group item can appear in a concurrent group set. Permissions Required The sec_rgy_pgo_add() routine requires the i (insert) permission on the parent directory in which the the PGO item is to be created. NOTES An account can be added to the registry database only when all its constituent PGO items are already in the database, and the appropriate membership relationships between them are established. For example, to establish an account with principal name tom, group name writers, and organization name hp, all three names must exist as independent PGO items in the database. Furthermore, tom must be a member of writers, which must be a member of hp. (See sec_rgy_acct_add() to add an account to the registry.) FILES SYS$COMMON:[DCE$LIBRARY]PGO.IDL The idl file from which dce/pgo.h was derived. ERRORS sec_rgy_not_authorized The client program is not authorized to add the specified PGO item. sec_rgy_object_exists A PGO item already exists with the name given in name. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_pgo_delete sec_rgy_pgo_rename sec_rgy_pgo_replace sec_rgy_acct_add 4 sec_rgy_pgo_add_member NAME sec_rgy_pgo_add_member - Adds a person to a group or organization SYNOPSIS #include void sec_rgy_pgo_add_member( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, sec_rgy_name_t go_name, sec_rgy_name_t person_name, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain This variable identifies the type of the person, group, or organization (PGO) item identified by the given name. The valid values are as follows: sec_rgy_domain_group The go_name parameter identifies a group. sec_rgy_domain_org The go_name parameter identifies an organization. go_name A character string (type sec_rgy_name_t) containing the name of the group or organization to which the specified person will be added. person_name A character string (type sec_rgy_name_t) containing the name of the person to be added to the membership list of the group or organization specified by go_name. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_pgo_add_member() routine adds a member to the membership list of a group or organization in the registry database. Permissions Required The sec_rgy_pgo_add_member() routine requires the M (Member_list) permission on the group or organization item specified by go_name. If go_name specifies a group, the routine also requires the g (groups) permission on the principal person_name. NOTES An account can be added to the registry database only when all its constituent PGO items are already in the database, and the appropriate membership relationships between them are established. For example, to establish an account with person name tom, group name writers, and organization name hp, all three names must exist as independent PGO items in the database. Furthermore, tom must be a member of writers, which must be a member of hp. (See the sec_rgy_acct_add() routine to add an account to the registry.) FILES SYS$COMMON:[DCE$LIBRARY]PGO.IDL The idl file from which dce/pgo.h was derived. ERRORS sec_rgy_not_authorized The client program is not authorized to add members to the specified group or organization. sec_rgy_bad_domain An invalid domain was specified. A member can be added only to a group or organization, not a person. sec_rgy_object_not_found The registry server could not find the specified name. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_pgo_add sec_rgy_pgo_delete_member sec_rgy_pgo_get_members sec_rgy_pgo_is_member 4 sec_rgy_pgo_delete NAME sec_rgy_pgo_delete - Deletes a PGO item from the registry database SYNOPSIS #include void sec_rgy_pgo_delete( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, sec_rgy_name_t name, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain This variable identifies the type of principal, group, or organization (PGO) item identified by the given name. The valid values are as follows: sec_rgy_domain_person The name identifies a principal. sec_rgy_domain_group The name identifies a group. sec_rgy_domain_org The name identifies an organization. name A pointer to a sec_rgy_name_t character string containing the name of the PGO item to be deleted. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_pgo_delete() routine deletes a PGO item from the registry database. Any account depending on the deleted PGO item is also deleted. Permissions Required The sec_rgy_pgo_delete() routine requires the following permissions: + The d (delete) permission on the parent directory that contains the the PGO item to be deleted. + The D (Delete_object) permission on the PGO item itself. FILES SYS$COMMON:[DCE$LIBRARY]PGO.IDL The idl file from which dce/pgo.h was derived. ERRORS sec_rgy_not_authorized The client program is not authorized to delete the specified item. sec_rgy_object_not_found The registry server could not find the specified item. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_pgo_add 4 sec_rgy_pgo_delete_member NAME sec_rgy_pgo_delete_member - Deletes a member of a group or organization SYNOPSIS #include void sec_rgy_pgo_delete_member( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, sec_rgy_name_t go_name, sec_rgy_name_t person_name, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain This variable identifies the type of the person, group, or organization (PGO) item identified by the given name. The valid values are as follows: sec_rgy_domain_group The go_name parameter identifies a group. sec_rgy_domain_org The go_name parameter identifies an organization. go_name A character string (type sec_rgy_name_t) containing the name of the group or organization from which the specified person will be deleted. person_name A character string (type sec_rgy_name_t) containing the name of the person to be deleted from the membership list of the group or organization specified by go_name. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_pgo_delete_member() routine deletes a member from the membership list of a group or organization. Any accounts in which the person holds the deleted group or organization membership are also deleted. Permissions Required The sec_rgy_pgo_delete_member() routine requires the M (Member_list) permission on the group or organization item specified by go_name. FILES SYS$COMMON:[DCE$LIBRARY]PGO.IDL The idl file from which dce/pgo.h was derived. ERRORS sec_rgy_not_authorized The client program is not authorized to delete the specified member. sec_rgy_bad_domain An invalid domain was specified. Members can exist only for groups and organizations, not for persons. sec_rgy_object_not_found The specified group or organization was not found. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_pgo_add sec_rgy_pgo_add_member 4 sec_rgy_pgo_get_by_eff_unix_num NAME sec_rgy_pgo_get_by_eff_unix_num - Returns the name and data for a PGO item identified by its effective UNIX number SYNOPSIS #include void sec_rgy_pgo_get_by_eff_unix_num( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, sec_rgy_name_t scope, signed32 unix_id, boolean32 allow_aliases, sec_rgy_cursor_t *item_cursor, sec_rgy_pgo_item_t *pgo_item, sec_rgy_name_t name, boolean32 *overridden, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain This variable identifies the type of the principal, group, or organization (PGO) item identified by the given name. The valid values are as follows: sec_rgy_domain_person The UNIX number identifies a principal. sec_rgy_domain_group The UNIX number identifies a group. Note that this function does not support the value sec_rgy_domain_org. scope A character string (type sec_rgy_name_t) containing the scope of the desired search. The registry database is designed to accommodate a tree-structured name hierarchy. The scope of a search is the name of the branch under which the search takes place. For example, all names in a registry might start with /alpha, and be divided further into /beta or /gamma. To search only the part of the database under /beta, the scope of the search would be /alpha/beta, and any resulting PGO items would have names beginning with this string. Note that these naming conventions need not have anything to do with group or organization PGO item membership lists. unix_id The UNIX number of the desired registry PGO item. allow_aliases A boolean32 value indicating whether to search for a primary PGO item, or whether the search can be satisfied with an alias. If TRUE, the routine returns the next entry found for the PGO item. If FALSE, the routine returns only the primary entry. Input/Output item_cursor An opaque pointer indicating a specific PGO item entry in the registry database. The sec_rgy_pgo_get_next() routine returns the PGO item indicated by item_cursor, and advances the cursor to point to the next item in the database. When the end of the list of entries is reached, the routine returns the value sec_rgy_no_more_entries in the status parameter. Use sec_rgy_cursor_reset() to reset the cursor. Output pgo_item A pointer to a sec_rgy_pgo_item_t structure to receive the data for the returned PGO item. The data in this structure includes the PGO item's name, UUID, UNIX number (if any), and administrative data, such as whether the item, if a principal, may have a concurrent group set. The data is as it appears in the registry, for that UNIX number. name A pointer to a sec_rgy_name_t character string containing the returned name for the PGO item. overridden A pointer to a boolean32 value indicating whether or not the supplied UNIX number has an entry in the local override file (passwd_override or group_override). [NOT APPLICABLE ON OPENVMS] status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_pgo_get_by_eff_unix_num() routine returns the name and data for a PGO item. The desired item is identified by its type (domain) and its UNIX number. This routine is similar to the sec_rgy_pgo_get_by_unix_num() routine. The difference between the routines is that on UNIX, sec_rgy_pgo_get_by_eff_unix_num() first searches the local override files for the respective name_domain for a match with the supplied UNIX number. If an override match is found, and an account or group name is found in that entry, then that name is used to obtain PGO data from the registry and the value of the overridden parameter is set to TRUE. The item_cursor parameter specifies the starting point for the search through the registry database. It provides an automatic place holder in the database. The routine automatically updates this variable to point to the next PGO item after the returned item. The returned cursor location can be supplied on a subsequent database access call that also uses a PGO item cursor. Permissions Required The sec_rgy_pgo_get_by_eff_unix_num() routine requires the r (read) permission on the PGO item to be viewed. CAUTIONS There are several different types of cursors used in the registry Application Programmer Interface (API). Some cursors point to PGO items, others point to members in a membership list, and others point to account data. Do not use a cursor for one sort of object in a call expecting another sort of object. For example, you cannot use the same cursor on a call to sec_rgy_acct_get_projlist() and sec_rgy_pgo_get_next(). The behavior in this case is undefined. Furthermore, cursors are specific to a server. A cursor pointing into one replica of the registry database is useless as a pointer into another replica. Use sec_rgy_cursor_reset() to renew a cursor for use with another call or for another server. FILES SYS$COMMON:[DCE$LIBRARY]PGO.IDL The idl file from which dce/pgo.h was derived. ERRORS sec_rgy_no_more_entries The cursor is at the end of the list of PGO items. sec_rgy_object_not_found The specified PGO item was not found. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_pgo_add sec_rgy_pgo_get_by_id sec_rgy_pgo_get_by_name sec_rgy_pgo_get_by_unix_num sec_rgy_pgo_get_next sec_rgy_pgo_id_to_name sec_rgy_pgo_id_to_unix_num sec_rgy_pgo_name_to_id sec_rgy_pgo_unix_num_to_id sec_rgy_cursor_reset 4 sec_rgy_pgo_get_by_id NAME sec_rgy_pgo_get_by_id - Returns the name and data for a PGO item identified by its UUID SYNOPSIS #include void sec_rgy_pgo_get_by_id( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, sec_rgy_name_t scope, uuid_t *item_id, boolean32 allow_aliases, sec_rgy_cursor_t *item_cursor, sec_rgy_pgo_item_t *pgo_item, sec_rgy_name_t name, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain This variable identifies the type of the principal, group, or organization (PGO) item identified by the given name. The valid values are as follows: sec_rgy_domain_person The UUID identifies a principal. sec_rgy_domain_group The UUID identifies a group. sec_rgy_domain_org The UUID identifies an organization. scope A character string (type sec_rgy_name_t) containing the scope of the desired search. The registry database is designed to accommodate a tree-structured name hierarchy. The scope of a search is the name of the branch under which the search takes place. For example, all names in a registry might start with /alpha, and be divided further into /beta or /gamma. To search only the part of the database under /beta, the scope of the search would be /alpha/beta, and any resulting PGO items would have names beginning with this string. Note that these naming conventions need not have anything to do with group or organization PGO item membership lists. item_id A pointer to the uuid_t variable containing the UUID (Unique Universal Identifier) of the desired PGO item. allow_aliases A boolean32 value indicating whether to search for a primary PGO item, or whether the search can be satisfied with an alias. If TRUE, the routine returns the next entry found for the PGO item. If FALSE, the routine returns only the primary entry. Input/Output item_cursor An opaque pointer indicating a specific PGO item entry in the registry database. The sec_rgy_pgo_get_by_id() routine returns the PGO item indicated by item_cursor, and advances the cursor to point to the next item in the database. When the end of the list of entries is reached, the routine returns sec_rgy_no_more_entries in the status parameter. Use sec_rgy_cursor_reset() to reset the cursor. Output pgo_item A pointer to a sec_rgy_pgo_item_t structure to receive the data for the returned PGO item. The data in this structure includes the PGO item's name, UUID, UNIX number (if any), and administrative data, such as whether the item, if a principal, may have a concurrent group set. name A pointer to a sec_rgy_name_t character string containing the returned name for the PGO item. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_pgo_get_by_id() routine returns the name and data for a PGO item. The desired item is identified by its type (domain) and its UUID. The item_cursor parameter specifies the starting point for the search through the registry database. It provides an automatic place holder in the database. The routine automatically updates this variable to point to the next PGO item after the returned item. The returned cursor location can be supplied on a subsequent database access call that also uses a PGO item cursor. Permissions Required The sec_rgy_pgo_get_by_id() routine requires the r (read) permission on the PGO item to be viewed. CAUTIONS There are several different types of cursors used in the registry Application Programmer Interface (API). Some cursors point to PGO items, others point to members in a membership list, and others point to account data. Do not use a cursor for one sort of object in a call expecting another sort of object. For example, you cannot use the same cursor on a call to sec_rgy_acct_get_projlist() and sec_rgy_pgo_get_next(). The behavior in this case is undefined. Furthermore, cursors are specific to a server. A cursor pointing into one replica of the registry database is useless as a pointer into another replica. Use sec_rgy_cursor_reset() to renew a cursor for use with another call or for another server. FILES SYS$COMMON:[DCE$LIBRARY]PGO.IDL The idl file from which dce/pgo.h was derived. ERRORS sec_rgy_no_more_entries The cursor is at the end of the list of PGO items. sec_rgy_object_not_found The specified PGO item was not found. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_pgo_add sec_rgy_pgo_get_by_name sec_rgy_pgo_get_by_unix_num sec_rgy_pgo_get_next sec_rgy_pgo_id_to_name sec_rgy_pgo_id_to_unix_num sec_rgy_pgo_name_to_id sec_rgy_pgo_unix_num_to_id sec_rgy_cursor_reset 4 sec_rgy_pgo_get_by_name NAME sec_rgy_pgo_get_by_name - Returns the data for a named PGO item SYNOPSIS #include void sec_rgy_pgo_get_by_name( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, sec_rgy_name_t pgo_name, sec_rgy_cursor_t *item_cursor, sec_rgy_pgo_item_t *pgo_item, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain This variable identifies the type of the principal, group, or organization (PGO) item identified by the given name. The valid values are as follows: sec_rgy_domain_person The name identifies a principal. sec_rgy_domain_group The name identifies a group. sec_rgy_domain_org The name identifies an organization. pgo_name A character string (type sec_rgy_name_t) containing the name of the principal, group, or organization to search for. Input/Output item_cursor An opaque pointer indicating a specific PGO item entry in the registry database. The sec_rgy_pgo_get_by_name() routine returns the PGO item indicated by item_cursor, and advances the cursor to point to the next item in the database. When the end of the list of entries is reached, the routine returns the value sec_rgy_no_more_entries in the status parameter. Use sec_rgy_cursor_reset() to reset the cursor. Output pgo_item A pointer to a sec_rgy_pgo_item_t structure to receive the data for the returned PGO item. The data in this structure includes the PGO item's name, UUID, UNIX number (if any), and administrative data, such as whether the item, if a principal, may have a concurrent group set. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_pgo_get_by_name() routine returns the data for a named PGO item from the registry database. The desired item is identified by its type (name_domain) and name. The item_cursor parameter specifies the starting point for the search through the registry database. It provides an automatic place holder in the database. The routine automatically updates this variable to point to the next PGO item after the returned item. The returned cursor location can be supplied on a subsequent database access call that also uses a PGO item cursor. Permissions Required The sec_rgy_pgo_get_by_name() routine requires the r (read) permission on the PGO item to be viewed. CAUTIONS There are several different types of cursors used in the registry Application Programmer Interface (API). Some cursors point to PGO items, others point to members in a membership list, and others point to account data. Do not use a cursor for one sort of object in a call expecting another sort of object. For example, you cannot use the same cursor on a call to sec_rgy_acct_get_projlist() and sec_rgy_pgo_get_next(). The behavior in this case is undefined. Furthermore, cursors are specific to a server. A cursor pointing into one replica of the registry database is useless as a pointer into another replica. Use sec_rgy_cursor_reset() to renew a cursor for use with another call or for another server. FILES SYS$COMMON:[DCE$LIBRARY]PGO.IDL The idl file from which dce/pgo.h was derived. ERRORS sec_rgy_no_more_entries The cursor is at the end of the list of PGO items. sec_rgy_object_not_found The specified PGO item was not found. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_pgo_add sec_rgy_pgo_get_by_id sec_rgy_pgo_get_by_unix_num sec_rgy_pgo_get_next sec_rgy_pgo_id_to_name sec_rgy_pgo_id_to_unix_num sec_rgy_pgo_name_to_id sec_rgy_pgo_unix_num_to_id sec_rgy_cursor_reset 4 sec_rgy_pgo_get_by_unix_num NAME sec_rgy_pgo_get_by_unix_num - Returns the name and data for a PGO item identified by its UNIX ID SYNOPSIS #include void sec_rgy_pgo_get_by_unix_num( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, sec_rgy_name_t scope, signed32 unix_id, boolean32 allow_aliases, sec_rgy_cursor_t *item_cursor, sec_rgy_pgo_item_t *pgo_item, sec_rgy_name_t name, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain This variable identifies the type of the principal, group, or organization (PGO) item identified by the given name. The valid values are as follows: sec_rgy_domain_person The UNIX number identifies a principal. sec_rgy_domain_group The UNIX number identifies a group. sec_rgy_domain_org The UNIX number identifies an organization. scope A character string (type sec_rgy_name_t) containing the scope of the desired search. The registry database is designed to accommodate a tree-structured name hierarchy. The scope of a search is the name of the branch under which the search takes place. For example, all names in a registry might start with /alpha, and be divided further into /beta or /gamma. To search only the part of the database under /beta, the scope of the search would be /alpha/beta, and any resulting PGO items would have names beginning with this string. Note that these naming conventions need not have anything to do with group or organization PGO item membership lists. unix_id The UNIX number of the desired registry PGO item. allow_aliases A boolean32 value indicating whether to search for a primary PGO item, or whether the search can be satisfied with an alias. If TRUE, the routine returns the next entry found for the PGO item. If FALSE, the routine returns only the primary entry. Input/Output item_cursor An opaque pointer indicating a specific PGO item entry in the registry database. The sec_rgy_pgo_get_by_unix_num() routine returns the PGO item indicated by item_cursor, and advances the cursor to point to the next item in the database. When the end of the list of entries is reached, the routine returns the value sec_rgy_no_more_entries in the status parameter. Use sec_rgy_cursor_reset() to reset the cursor. Output pgo_item A pointer to a sec_rgy_pgo_item_t structure to receive the data for the returned PGO item. The data in this structure includes the PGO item's name, UUID, UNIX number (if any), and administrative data, such as whether the item, if a principal, may have a concurrent group set. name A pointer to a sec_rgy_name_t character string containing the returned name for the PGO item. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_pgo_get_by_unix_num() routine returns the name and data for a PGO item. The desired item is identified by its type (domain) and its UNIX number. The item_cursor parameter specifies the starting point for the search through the registry database. It provides an automatic place holder in the database. The routine automatically updates this variable to point to the next PGO item after the returned item. The returned cursor location can be supplied on a subsequent database access call that also uses a PGO item cursor. Permissions Required The sec_rgy_pgo_get_by_unix_num() routine requires the r (read) permission on the PGO item to be viewed. CAUTIONS There are several different types of cursors used in the registry Application Programmer Interface (API). Some cursors point to PGO items, others point to members in a membership list, and others point to account data. Do not use a cursor for one sort of object in a call expecting another sort of object. For example, you cannot use the same cursor on a call to sec_rgy_acct_get_projlist() and sec_rgy_pgo_get_next(). The behavior in this case is undefined. Furthermore, cursors are specific to a server. A cursor pointing into one replica of the registry database is useless as a pointer into another replica. Use sec_rgy_cursor_reset() to renew a cursor for use with another call or for another server. FILES SYS$COMMON:[DCE$LIBRARY]PGO.IDL The idl file from which dce/pgo.h was derived. ERRORS sec_rgy_no_more_entries The cursor is at the end of the list of PGO items. sec_rgy_object_not_found The specified PGO item was not found. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_pgo_add sec_rgy_pgo_get_by_id sec_rgy_pgo_get_by_name sec_rgy_pgo_get_next sec_rgy_pgo_id_to_name sec_rgy_pgo_id_to_unix_num sec_rgy_pgo_name_to_id sec_rgy_pgo_unix_num_to_id sec_rgy_cursor_reset 4 sec_rgy_pgo_get_members NAME sec_rgy_pgo_get_members - Returns the membership list for a specified group or organization or returns the set of groups in which the specified principal is a member. SYNOPSIS #include void sec_rgy_pgo_get_members( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, sec_rgy_name_t go_name, sec_rgy_cursor_t *member_cursor, signed32 max_members, sec_rgy_member_t member_list[], signed32 *number_supplied, signed32 *number_members, error_status_t *status); PARAMETERS Input context An opaque handle bound to a secd server. Use sec_rgy_site_open() to acquire a bound handle. name_domain This variable specifies whether go_name identifies a principal, group, or organization. The valid values are as follows: sec_rgy_domain_group The go_name parameter identifies a group. sec_rgy_domain_org The go_name parameter identifies an organization. sec_rgy_domain_person The go_name parameter identifies an principal. go_name A character string (type sec_rgy_name_t) that contains the name of a group, organization, or principal. If go_name is the name of a group or organization, the call returns the group's or organization's member list. If go_name is the name of a principal, the call returns a list of all groups in which the principal is a member. (Contrast this with the sec_rgy_acct_get_proj call, which returns only those groups in which the principal is a member and that have been marked to be included in the principal's project list.) max_members A signed32 variable containing the allocated dimension of the member_list[] array. This is the maximum number of members or groups that can be returned by a single call. Input/Output member_cursor An opaque pointer to a specific entry in the membership list or list of groups. The returned list begins with the entry specified by member_cursor. Upon return, the cursor points to the next entry after the last one returned. If there are no more entries, the routine returns the value sec_rgy_no_more_entries in the status parameter. Use sec_rgy_cursor_reset() to reset the cursor to the beginning of the list. Output member_list[] An array of character strings to receive the returned member or group names. The size allocated for the array is given by max_number. If this value is less than the total number of members or group names, multiple calls must be made to return all of the members or groups. number_supplied A pointer to a signed32 variable to receive the number of members or groups actually returned in member_list[]. number_members A pointer to a signed32 variable to receive the total number of members or groups. If this number is greater than number_supplied, multiple calls to sec_rgy_pgo_get_members() are necessary. Use the member_cursor parameter to coordinate successive calls. status A pointer to the completion status. On successful completion, status is assigned error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_pgo_get_members() routine returns a list of the members in the specified group or organization, or a list of groups in which a specified principal is a member. The member_cursor parameter specifies the starting point for the search through the registry database. It provides an automatic place holder in the database. The routine automatically updates member_cursor to point to the next member or group (if any) after the returned list. If not all of the members or groups are returned, the updated cursor can be supplied on successive calls to return the remainder of the list. Permissions Required The sec_rgy_pgo_get_members() routine requires the r (read) permission on the group, organization, or principal object specified by go_name. CAUTIONS There are several different types of cursors used in the registry Application Programmer Interface (API). Some cursors point to PGO items, others point to members in a membership list, and others point to account data. Do not use a cursor for one sort of object in a call expecting another sort of object. For example, you cannot use the same cursor on a call to sec_rgy_acct_get_projlist() and sec_rgy_pgo_get_next(). The behavior in this case is undefined. Furthermore, cursors are specific to a server. A cursor pointing into one replica of the registry database is useless as a pointer into another replica. Use sec_rgy_cursor_reset() to renew a cursor for use with another call or for another server. RETURN VALUES The routine returns: + The names of the groups or members in member_list[] + The number of members or groups returned by the call in number_supplied + The total number of members in the group or organization, or the total number of groups in which the principal is a member in number_members FILES SYS$COMMON:[DCE$LIBRARY]PGO.IDL The idl file from which dce/pgo.h was derived. ERRORS sec_rgy_no_more_entries The cursor points to the end of the membership list for a group or organization or to the end of the list of groups for a principal. sec_rgy_object_not_found The specified group, organization, or principal could not be found. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_pgo_add_member sec_rgy_cursor_reset sec_rgy_pgo_is_member sec_rgy_acct_get_proj 4 sec_rgy_pgo_get_next NAME sec_rgy_pgo_get_next - Returns the next PGO item in the registry database SYNOPSIS #include void sec_rgy_pgo_get_next( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, sec_rgy_name_t scope, sec_rgy_cursor_t *item_cursor, sec_rgy_pgo_item_t *pgo_item, sec_rgy_name_t name, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain This variable identifies the type of the principal, group, or organization (PGO) item identified by the given name. The valid values are as follows: sec_rgy_domain_person Returns the next principal item. sec_rgy_domain_group Returns the next group item. sec_rgy_domain_org Returns the next organization item. scope A character string (type sec_rgy_name_t) containing the scope of the desired search. The registry database is designed to accommodate a tree-structured name hierarchy. The scope of a search is the name of the branch under which the search takes place. For example, all names in a registry might start with /alpha, and be divided further into /beta or /gamma. To search only the part of the database under /beta, the scope of the search would be /alpha/beta, and any resulting PGO items would have names beginning with this string. Note that these naming conventions need not have anything to do with group or organization PGO item membership lists. Input/Output item_cursor An opaque pointer indicating a specific PGO item entry in the registry database. The sec_rgy_pgo_get_next() routine returns the PGO item indicated by item_cursor, and advances the cursor to point to the next item in the database. When the end of the list of entries is reached, the routine returns the value sec_rgy_no_more_entries in the status parameter. Use sec_rgy_cursor_reset() to reset the cursor. Output pgo_item A pointer to a sec_rgy_pgo_item_t structure to receive the data for the returned PGO item. The data in this structure includes the PGO item's name, UUID, UNIX number (if any), and administrative data, such as whether the item, if a principal, may have a concurrent group set. name A pointer to a sec_rgy_name_t character string containing the name of the returned PGO item. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_pgo_get_next() routine returns the data and name for the PGO in the registry database indicated by item_cursor. It also advances the cursor to point to the next PGO item in the database. Successive calls to this routine return all the PGO items in the database of the specified type (given by name_domain), in storage order. The PGO data consists of the following: + The Universal Unique Identifier (UUID) of the PGO item. + The UNIX number for the PGO item. + The quota for subaccounts. + The full name of the PGO item. + Flags indicating whether - A principal item is an alias. - The PGO item can be deleted. - A principal item can have a concurrent group set. - A group item can appear on a concurrent group set. Permissions Required The sec_rgy_pgo_get_next() routine requires the r (read) permission on the PGO item to be viewed. CAUTIONS There are several different types of cursors used in the registry Application Programmer Interface (API). Some cursors point to PGO items, others point to members in a membership list, and others point to account data. Do not use a cursor for one sort of object in a call expecting another sort of object. For example, you cannot use the same cursor on a call to sec_rgy_acct_get_projlist() and sec_rgy_pgo_get_next(). The behavior in this case is undefined. Furthermore, cursors are specific to a server. A cursor pointing into one replica of the registry database is useless as a pointer into another replica. Use sec_rgy_cursor_reset() to renew a cursor for use with another call or for another server. RETURN VALUES The routine returns the data for the returned PGO item in pgo_item and the name in name. FILES SYS$COMMON:[DCE$LIBRARY]PGO.IDL The idl file from which dce/pgo.h was derived. ERRORS sec_rgy_no_more_entries The cursor is at the end of the list of PGO items. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_pgo_add sec_rgy_cursor_reset sec_rgy_pgo_get_by_id sec_rgy_pgo_get_by_name sec_rgy_pgo_get_by_unix_num sec_rgy_pgo_id_to_unix_num sec_rgy_pgo_unix_num_to_id 4 sec_rgy_pgo_id_to_name NAME sec_rgy_pgo_id_to_name - Returns the name for a PGO item identified by its UUID SYNOPSIS #include void sec_rgy_pgo_id_to_name( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, uuid_t *item_id, sec_rgy_name_t pgo_name, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain This variable identifies the type of the principal, group, or organization (PGO) item identified by the given name. The valid values are as follows: sec_rgy_domain_person The item_id parameter identifies a principal. sec_rgy_domain_group The item_id parameter identifies a group. sec_rgy_domain_org The item_id parameter identifies an organization. item_id A pointer to the uuid_t variable containing the input UUID (Unique Universal Identifier). Output pgo_name A character string (type sec_rgy_name_t) containing the name of the principal, group, or organization with the input UUID. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_pgo_id_to_name() routine returns the name of the PGO item having the specified UUID. Permissions Required The sec_rgy_pgo_id_to_name() routine requires at least one permission of any kind on the PGO item to be viewed. FILES SYS$COMMON:[DCE$LIBRARY]PGO.IDL The idl file from which dce/pgo.h was derived. ERRORS sec_rgy_object_not_found No item with the specified UUID could be found. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_pgo_add sec_rgy_pgo_get_by_id sec_rgy_pgo_get_by_name sec_rgy_pgo_get_by_unix_num sec_rgy_pgo_id_to_unix_num sec_rgy_pgo_name_to_id sec_rgy_pgo_unix_num_to_id 4 sec_rgy_pgo_id_to_unix_num NAME sec_rgy_pgo_id_to_unix_num - Returns the UNIX number for a PGO item identified by its UUID SYNOPSIS #include void sec_rgy_pgo_id_to_unix_num( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, uuid_t *item_id, signed32 *item_unix_id, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain This variable identifies the type of the principal, group, or organization (PGO) item identified by the given name. The valid values are as follows: sec_rgy_domain_person The item_id parameter identifies a principal. sec_rgy_domain_group The item_id parameter identifies a group. sec_rgy_domain_org The item_id parameter identifies an organization. item_id A pointer to the uuid_t variable containing the input UUID (Unique Universal Identifier). Output item_unix_id A pointer to the signed32 variable to receive the returned UNIX number for the PGO item. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_pgo_id_to_unix_num() routine returns the UNIX number for the PGO item having the specified UUID. FILES SYS$COMMON:[DCE$LIBRARY]PGO.IDL The idl file from which dce/pgo.h was derived. ERRORS sec_rgy_object_not_found No item with the specified UUID could be found. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_pgo_add sec_rgy_pgo_get_by_id sec_rgy_pgo_get_by_name sec_rgy_pgo_get_by_unix_num sec_rgy_pgo_id_to_name sec_rgy_pgo_name_to_id sec_rgy_pgo_unix_num_to_id 4 sec_rgy_pgo_is_member NAME sec_rgy_pgo_is_member - Checks group or organization membership SYNOPSIS #include boolean32 sec_rgy_pgo_is_member( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, sec_rgy_name_t go_name, sec_rgy_name_t person_name, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain This variable identifies the type of the principal, group, or organization (PGO) item identified by the given name. The valid values are as follows: sec_rgy_domain_group The go_name parameter identifies a group. sec_rgy_domain_org The go_name parameter identifies an organization. go_name A character string (type sec_rgy_name_t) containing the name of the group or organization whose membership list is in question. person_name A character string (type sec_rgy_name_t) containing the name of the principal whose membership in the group or organization specified by go_name is in question. Output status A pointer to the completion status. On successful completion, status is assigned error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_pgo_is_member() routine tests whether the specified principal is a member of the named group or organization. Permissions Required The sec_rgy_pgo_is_member() routine requires the t (test) permission on the group or organization item specified by go_name. RETURN VALUES The routine returns TRUE if the principal is a member of the named group or organization. If the principal is not a member, the routine returns FALSE. FILES SYS$COMMON:[DCE$LIBRARY]PGO.IDL The idl file from which dce/pgo.h was derived. ERRORS sec_rgy_object_not_found The named group or organization was not found. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_pgo_add_member sec_rgy_pgo_get_members 4 sec_rgy_pgo_name_to_id NAME sec_rgy_pgo_name_to_id - Returns the UUID for a named PGO item SYNOPSIS #include void sec_rgy_pgo_name_to_id( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, sec_rgy_name_t pgo_name, uuid_t *item_id, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain This variable identifies the type of the principal, group, or organization (PGO) item identified by the given name. The valid values are as follows: sec_rgy_domain_person The name identifies a principal. sec_rgy_domain_group The name identifies a group. sec_rgy_domain_org The name identifies an organization. pgo_name A character string (type sec_rgy_name_t) containing the name of the principal, group, or organization whose UUID is desired. Output item_id A pointer to the uuid_t variable containing the UUID (Unique Universal Identifier) of the resulting PGO item. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_pgo_name_to_id() routine returns the UUID associated with the named PGO item. FILES SYS$COMMON:[DCE$LIBRARY]PGO.IDL The idl file from which dce/pgo.h was derived. ERRORS sec_rgy_object_not_found The specified PGO item could not be found. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_pgo_add sec_rgy_pgo_get_by_id sec_rgy_pgo_get_by_name sec_rgy_pgo_get_by_unix_num sec_rgy_pgo_id_to_name sec_rgy_pgo_id_to_unix_num sec_rgy_pgo_unix_num_to_id 4 sec_rgy_pgo_name_to_unix_num NAME sec_rgy_pgo_name_to_unix_num - Returns the UNIX number for a PGO item identified by its name SYNOPSIS #include void sec_rgy_pgo_name_to_unix_num( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, sec_rgy_name_t pgo_name, signed32 *item_unix_id, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain This variable identifies the type of the principal, group, or organization (PGO) item identified by the given name. The valid values are as follows: sec_rgy_domain_person The name identifies a principal. sec_rgy_domain_group The name identifies a group. sec_rgy_domain_org The name identifies an organization. pgo_name A character string containing the name of the PGO item in question. Output item_unix_id A pointer to the signed32 variable to receive the returned UNIX number for the PGO item. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_pgo_name_to_unix_num() routine returns the UNIX number for the PGO item having the specified name. FILES SYS$COMMON:[DCE$LIBRARY]PGO.IDL The idl file from which dce/pgo.h was derived. ERRORS sec_rgy_object_not_found No item with the specified UUID could be found. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_pgo_add sec_rgy_pgo_get_by_id sec_rgy_pgo_get_by_name sec_rgy_pgo_get_by_unix_num sec_rgy_pgo_id_to_name sec_rgy_pgo_name_to_id sec_rgy_pgo_unix_num_to_id 4 sec_rgy_pgo_rename NAME sec_rgy_pgo_rename - Changes the name of a PGO item in the registry database SYNOPSIS #include void sec_rgy_pgo_rename( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, sec_rgy_name_t old_name, sec_rgy_name_t new_name, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain This variable identifies the type of the principal, group, or organization (PGO) item identified by the given name. The valid values are as follows: sec_rgy_domain_person The name identifies a principal. sec_rgy_domain_group The name identifies a group. sec_rgy_domain_org The name identifies an organization. old_name A pointer to a sec_rgy_name_t character string containing the existing name of the PGO item. new_name A pointer to a sec_rgy_name_t character string containing the new name for the PGO item. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_pgo_rename() routine renames a PGO item in the registry database. Permissions Required If the sec_rgy_pgo_rename() routine is performing a rename within a directory, it requires the n (name) permission on the old name of the PGO item. If the routine is performing a move between directories, it requires the following permissions: + The d (delete) permission on the parent directory that contains the PGO item. + The n (name) permission on the old name of the PGO item. + The i (insert) permission on the parent directory in which the PGO item is to be added under the new name. FILES SYS$COMMON:[DCE$LIBRARY]PGO.IDL The idl file from which dce/pgo.h was derived. ERRORS sec_rgy_not_authorized The client program is not authorized to change the name of the specified PGO item. sec_rgy_object_not_found The registry server could not find the specified PGO item. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_pgo_add sec_rgy_pgo_replace 4 sec_rgy_pgo_replace NAME sec_rgy_pgo_replace - Replaces the data in an existing PGO item SYNOPSIS #include void sec_rgy_pgo_replace( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, sec_rgy_name_t pgo_name, sec_rgy_pgo_item_t *pgo_item, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain This variable identifies the type of the principal, group, or organization (PGO) item identified by the given name. The valid values are as follows: sec_rgy_domain_person The name identifies a principal. sec_rgy_domain_group The name identifies a group. sec_rgy_domain_org The name identifies an organization. pgo_name A character string (type sec_rgy_name_t) containing the name of the principal, group, or organization whose data is to be replaced. pgo_item A pointer to a sec_rgy_pgo_item_t structure containing the new data for the PGO item. The data in this structure includes the PGO item's name, UUID, UNIX number (if any), and administrative data, such as whether the item, if a principal, may have a concurrent group set. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_pgo_replace() routine replaces the data associated with a PGO item in the registry database. The UNIX ID and UUID of a PGO item cannot be replaced. To change the UNIX ID or UUID, the existing PGO item must be deleted and a new PGO item added in its place. The one exception to this rule is that the UNIX ID can be replaced in the PGO item for a cell principal. The reason for this exception is that the UUID for a cell principal does not contain an embedded UNIX ID. Permissions Required The sec_rgy_pgo_replace() routine requires at least one of the following permissions: + The m (mgmt_info) permission on the PGO item, if quota or flags is being set. + The f (fullname) permission on the PGO item, if fullname is being set. FILES SYS$COMMON:[DCE$LIBRARY]PGO.IDL The idl file from which dce/pgo.h was derived. ERRORS sec_rgy_not_authorized The client program is not authorized to replace the specified PGO item. sec_rgy_object_not_found No PGO item was found with the given name. sec_rgy_unix_id_changed The UNIX number of the PGO item was changed. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_pgo_add sec_rgy_pgo_delete sec_rgy_pgo_rename 4 sec_rgy_pgo_unix_num_to_id NAME sec_rgy_pgo_unix_num_to_id - Returns the UUID for a PGO item identified by its UNIX number SYNOPSIS #include void sec_rgy_pgo_unix_num_to_id( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, signed32 item_unix_id, uuid_t *item_id, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain This variable identifies the type of the principal, group, or organization (PGO) item identified by the given name. The valid values are as follows: sec_rgy_domain_person The item_unix_id parameter identifies a principal. sec_rgy_domain_group The item_unix_id parameter identifies a group. sec_rgy_domain_org The item_unix_id parameter identifies an organization. item_unix_id The signed32 variable containing the UNIX number for the PGO item. Output item_id A pointer to the uuid_t variable containing the UUID (Unique Universal Identifier) of the resulting PGO item. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_pgo_unix_num_to_id() routine returns the Universal Unique Identifier (UUID) for a PGO item that has the specified UNIX number. FILES SYS$COMMON:[DCE$LIBRARY]PGO.IDL The idl file from which dce/pgo.h was derived. ERRORS sec_rgy_object_not_found No item with the specified UNIX number could be found. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_pgo_add sec_rgy_pgo_get_by_id sec_rgy_pgo_get_by_name sec_rgy_pgo_get_by_unix_num sec_rgy_pgo_id_to_name sec_rgy_pgo_id_to_unix_num sec_rgy_pgo_name_to_id 4 sec_rgy_pgo_unix_num_to_name NAME sec_rgy_pgo_unix_num_to_name - Returns the name for a PGO item identified by its UNIX number SYNOPSIS #include void sec_rgy_pgo_unix_num_to_name( sec_rgy_handle_t context, sec_rgy_domain_t name_domain, signed32 item_unix_id, sec_rgy_name_t pgo_name, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name_domain The type of the principal, group, or organization (PGO) item identified by item_unix_id. Valid values are as follows: sec_rgy_domain_person The item_unix_id parameter identifies a principal. sec_rgy_domain_group The item_unix_id parameter identifies a group. sec_rgy_domain_org The item_unix_id parameter identifies an organization. item_unix_id The signed32 variable containing the UNIX number for the PGO item. Output pgo_name A character string containing the name of the PGO item in question. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_pgo_unix_num_to_name() routine returns the name for a PGO item that has the specified UNIX number. Permissions Required The sec_rgy_pgo_unix_num_to_name() routine requires at least one permission of any kind on the PGO item identified by item_unix_id. FILES SYS$COMMON:[DCE$LIBRARY]PGO.IDL The idl file from which dce/pgo.h was derived. ERRORS sec_rgy_object_not_found No item with the specified UNIX number could be found. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_pgo_add sec_rgy_pgo_get_by_id sec_rgy_pgo_get_by_name sec_rgy_pgo_get_by_unix_num sec_rgy_pgo_id_to_name sec_rgy_pgo_id_to_unix_num sec_rgy_pgo_name_to_id 4 sec_rgy_plcy_get_effective NAME sec_rgy_plcy_get_effective - Returns the effective policy for an organization SYNOPSIS #include void sec_rgy_plcy_get_effective( sec_rgy_handle_t context, sec_rgy_name_t organization, sec_rgy_plcy_t *policy_data, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. organization A character string (type sec_rgy_name_t) containing the name of the organization for which the policy data is to be returned. If this string is empty, the routine returns the registry's policy data. Output policy_data A pointer to the sec_rgy_plcy_t structure to receive the authentication policy. This structure contains the minimum length of a user's password, the lifetime of a password, the expiration date of a password, the lifetime of the entire account, and some flags describing limitations on the password spelling. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_plcy_get_effective() routine returns the effective policy for the specified organization. The effective policy data is the most restrictive combination of the registry and the organization policies. The policy data consists of the following: + The password expiration date. This is the date on which account passwords will expire. + The minimum length allowed for account passwords. + The period of time (life span) for which account passwords will be valid. + The period of time (life span) for which accounts will be valid. + Flags indicating whether account passwords can consist entirely of spaces or entirely of alphanumeric characters. Permissions Required The sec_rgy_plcy_get_effective() routine requires the r (read) permission on the policy object from which the data is to be returned. If an organization is specified, the routine also requires the r (read) permission on the organization. NOTES If no organization is specified, the routine returns the registry's policy data. To return the effective policy, an organization must be specified. This is because the routine compares the registry's policy data with that of the organization to determine which is more restrictive. FILES SYS$COMMON:[DCE$LIBRARY]POLICY.IDL The idl file from which dce/policy.h was derived. ERRORS sec_rgy_object_not_found The registry server could not find the specified organization. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_plcy_get_info sec_rgy_plcy_set_info 4 sec_rgy_plcy_get_info NAME sec_rgy_plcy_get_info - Returns the policy for an organization SYNOPSIS #include void sec_rgy_plcy_get_info( sec_rgy_handle_t context, sec_rgy_name_t organization, sec_rgy_plcy_t *policy_data, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. organization A character string (type sec_rgy_name_t) containing the name of the organization for which the policy data is to be returned. If this string is empty, the routine returns the registry's policy data. Output policy_data A pointer to the sec_rgy_plcy_t structure to receive the authentication policy. This structure contains the minimum length of a user's password, the lifetime of a password, the expiration date of a password, the lifetime of the entire account, and some flags describing limitations on the password spelling. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_plcy_get_info() routine returns the policy data for the specified organization. If no organization is specified, the registry's policy data is returned. The policy data consists of the following: + The password expiration date. This is the date on which account passwords will expire. + The minimum length allowed for account passwords. + The period of time (life span) for which account passwords will be valid. + The period of time (life span) for which accounts will be valid. + Flags indicating whether account passwords can consist entirely of spaces or entirely of alphanumeric characters. Permissions Required The sec_rgy_plcy_get_info() routine requires the r (read) permission on the policy object or organization from which the data is to be returned. NOTES The returned policy may not be in effect if the overriding registry authorization policy is more restrictive. (See the sec_rgy_auth_plcy_get_effective() routine.) FILES SYS$COMMON:[DCE$LIBRARY]POLICY.IDL The idl file from which dce/policy.h was derived. ERRORS sec_rgy_object_not_found The registry server could not find the specified organization. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_plcy_get_effective_info sec_rgy_plcy_set_info 4 sec_rgy_plcy_set_info NAME sec_rgy_plcy_set_info - Sets the policy for an organization SYNOPSIS #include void sec_rgy_plcy_set_info( sec_rgy_handle_t context, sec_rgy_name_t organization, sec_rgy_plcy_t *policy_data, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. organization A character string (type sec_rgy_name_t) containing the name of the organization for which the policy data is to be returned. If this string is empty, the routine sets the registry's policy data. policy_data A pointer to the sec_rgy_plcy_t structure containing the authentication policy. This structure contains the minimum length of a user's password, the lifetime of a password, the expiration date of a password, the lifetime of the entire account, and some flags describing limitations on the password spelling. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_plcy_set_info() routine sets the authentication policy for a specified organization. If no organization is specified, the registry's policy data is set. Policy data can be returned or set for individual organizations and for the registry as a whole. Permissions Required The sec_rgy_plcy_set_info() routine requires the m (mgmt_info) permission on the policy object or organization for which the data is to be set. NOTES The policy set on an account may be less restrictive than the policy set for the registry as a whole. In this case, the changes in policy have no effect, since the effective policy is the most restrictive combination of the organization and registry authentication policies. (See the sec_rgy_auth_plcy_get_effective() routine.) FILES SYS$COMMON:[DCE$LIBRARY]POLICY.IDL The idl file from which dce/policy.h was derived. ERRORS sec_rgy_not_authorized The user is not authorized to perform this operation. sec_rgy_object_not_found The registry server could not find the specified organization. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_plcy_get_effective sec_rgy_plcy_get_info 4 sec_rgy_properties_get_info NAME sec_rgy_properties_get_info - Returns registry properties SYNOPSIS #include void sec_rgy_properties_get_info( sec_rgy_handle_t context, sec_rgy_properties_t *properties, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. Output properties A pointer to a sec_rgy_properties_t structure to receive the returned property information. A registry's property information contains information such as the default and minimum lifetime and other restrictions on privilege attribute certificates, the realm authentication name, and whether or not this replica of the registry supports updates. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_properties_get_info() routine returns a list of the registry properties. The property information consists of the following: read_version A stamp specifying the earliest version of the registry server software that can read from this registry. write_version A stamp specifying the earliest version of the registry server software that can write to this registry. minimum_ticket_lifetime The minimum period of time for which an authentication ticket remains valid. default_certificate_lifetime The default period of time for which an authentication certificate (ticket-granting ticket) remains valid. A process can request an authentication certificate with a longer lifetime. Note that the maximum lifetime for an authentication certificate cannot exceed the lifetime established by the effective policy for the requesting account. low_unix_id_person The lowest UNIX ID that can be assigned to a principal in the registry. low_unix_id_group The lowest UNIX ID that can be assigned to a group in the registry. low_unix_id_org The lowest UNIX ID that can be assigned to an organization in the registry. max_unix_id The maximum UNIX ID that can be used for any item in the registry. realm A character string naming the cell controlled by this registry. realm_uuid The UUID of the cell controlled by this registry. flags Flags indicating whether sec_rgy_prop_readonly If TRUE, the registry database is read-only. sec_rgy_prop_auth_cert_unbound If TRUE, privilege attribute certificates can be generated for use at any site. sec_rgy_prop_shadow_password If FALSE, passwords can be distributed over the network. If this flag is TRUE, passwords will be stripped from the returned data to the sec_rgy_acct_lookup(), and other calls that return an account's encoded password. sec_rgy_prop_embedded_unix_id All registry UUIDs contain embedded UNIX IDs. This implies that the UNIX ID of any registry object cannot be changed, since UUIDs are immutable. Permissions Required The sec_rgy_properties_get_info() routine requires the r (read) permission on the policy object from which the property information is to be returned. FILES SYS$COMMON:[DCE$LIBRARY]POLICY.IDL The idl file from which dce/policy.h was derived. ERRORS sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_properties_set_info 4 sec_rgy_properties_set_info NAME sec_rgy_properties_set_info - Sets registry properties SYNOPSIS #include void sec_rgy_properties_set_info( sec_rgy_handle_t context, sec_rgy_properties_t *properties, error_status_t *status); PARAMETERS Input context The registry server handle. An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. properties A pointer to a sec_rgy_properties_t structure containing the registry property information to be set. A registry's property information contains information such as the default and minimum lifetime and other restrictions on privilege attribute certificates, the realm authentication name, and whether or not this replica of the registry supports updates. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_properties_set_info() routine sets the registry properties. The property information consists of the following: read_version A stamp specifying the earliest version of the registry server software that can read from this registry. write_version A stamp specifying the earliest version of the registry server software that can write to this registry. minimum_ticket_lifetime The minimum period of time for which an authentication ticket remains valid. default_certificate_lifetime The default period of time for which an authentication certificate (ticket-granting ticket) remains valid. A process can request an authentication certificate with a longer lifetime. Note that the maximum lifetime for an authentication certificate cannot exceed the lifetime established by the effective policy for the requesting account. low_unix_id_person The lowest UNIX ID that can be assigned to a principal in the registry. low_unix_id_group The lowest UNIX ID that can be assigned to a group in the registry. low_unix_id_org The lowest UNIX ID that can be assigned to an organization in the registry. max_unix_id The maximum UNIX ID that can be used for any item in the registry. realm A character string naming the cell controlled by this registry. realm_uuid The UUID of the cell controlled by this registry. flags Flags indicating whether sec_rgy_prop_readonly If TRUE, the registry database is read-only. sec_rgy_prop_auth_cert_unbound If TRUE, privilege attribute certificates can be generated for use at any site. sec_rgy_prop_shadow_password If FALSE, passwords can be distributed over the network. If this flag is TRUE, passwords will be stripped from the returned data to the sec_rgy_acct_lookup(), and other calls that return an account's encoded password. sec_rgy_prop_embedded_unix_id All registry UUIDs contain embedded UNIX IDs. This implies that the UNIX ID of any registry object cannot be changed, since UUIDs are immutable. Permissions Required The sec_rgy_properties_set_info() routine requires the m (mgmt_info) permission on the policy object for which the property information is to be set. FILES SYS$COMMON:[DCE$LIBRARY]POLICY.IDL The idl file from which dce/policy.h was derived. ERRORS sec_rgy_not_authorized The user is not authorized to change the registry properties. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_properties_get_info 4 sec_rgy_site_bind NAME sec_rgy_site_bind - Binds to a registry site SYNOPSIS #include void sec_rgy_site_bind( unsigned_char_t *site_name, sec_rgy_bind_auth_info_t *auth_info, sec_rgy_handle_t *context, error_status_t *status); PARAMETERS Input site_name A character string (type unsigned_char_t) containing the name of the registry site to bind to. Supply this name in any of the following forms: + To randomly choose a site to bind to in the named cell, specify a cell name (for example, /.../r_d.com or /.: for the local cell) + To bind to a specific site in a specific cell, specify either the site's global name (for example, /.../r_d.com/subsys/dce/sec/rs_server_250_2) or the site's network address (for example, ncadg_ip_udp:15.22.144.248) auth_info A pointer to the sec_rgy_bind_auth_info_t structure that identifies the authentication protocol, protection level, and authorization protocol to use in establishing the binding. (See the rpc_binding_set_auth_info() routine). If the sec_rgy_bind_auth_info_t structure specifies authenticated rpc, the caller must have established a valid network identity for this call to succeed. Output context A pointer to a sec_rgy_handle_t variable. Upon return, this contains a registry server handle indicating ("bound to") the desired registry site. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_site_bind() call binds to a registry site at the security level specified by the auth_info parameter. The site_name parameter identifies the registry to use. If site_name is NULL, or a zero- length string, a registry site in the local cell is selected by the client agent. NOTES Like the sec_rgy_site_bind_query() routine, this routine binds arbitrarily to either an update or query site. Although update sites can accept queries, query sites cannot accept updates. To specifically select an update site, use sec_rgy_site_bind_update(). FILES SYS$COMMON:[DCE$LIBRARY]BINDING.IDL The idl file from which dce/binding.h was derived. ERRORS sec_login_s_no_current_context The caller does not have a valid network login context. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_site_open sec_rgy_cell_bind 4 sec_rgy_site_bind_query NAME sec_rgy_site_bind_query - Binds to a registry query site SYNOPSIS #include void sec_rgy_site_bind_query( unsigned_char_t *site_name, sec_rgy_bind_auth_info_t *auth_info, sec_rgy_handle_t *context, error_status_t *status); PARAMETERS Input site_name A character string (type unsigned_char_t) containing the name of the registry site to bind to. Supply this name in any of the following forms: + To randomly choose a site to bind to in the named cell, specify a cell name (for example, /.../r_d.com or /.: for the local cell) + To bind to a specific site in a specific cell, specify either the site's global name (for example, /.../r_d.com/subsys/dce/sec/rs_server_250_2) or the site's network address (for example, ncadg_ip_udp:15.22.144.248) auth_info A pointer to the sec_rgy_bind_auth_info_t structure that identifies the authentication protocol, protection level, and authorization protocol to use in establishing the binding. (See the rpc_binding_set_auth_info() routine). If the sec_rgy_bind_auth_info_t structure specifies authenticated rpc, the caller must have established a valid network identity for this call to succeed. Output context A pointer to a sec_rgy_handle_t variable. Upon return, this contains a registry server handle indicating ("bound to") the desired registry site. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_site_bind_query() routine binds to a registry query site at an arbitrary level of security. A registry query site is a satellite server that operates on a periodically updated copy of the main registry database. To change the registry database, it is necessary to change a registry update site, which then automatically updates its associated query sites. No changes can be made directly to a registry query database. The site_name parameter identifies the query site to use. If site_name is NULL, or a zero-length string, a query site in the local cell is selected by the client agent. The handle for the associated registry server is returned in context. NOTES Like sec_rgy_bind_open() routine, this routine binds arbitrarily to either an update or query site. Although update sites can accept queries, query sites cannot accept updates. To specifically select an update site, use sec_rgy_site_bind_update(). FILES SYS$COMMON:[DCE$LIBRARY]BINDING.IDL The idl file from which dce/binding.h was derived. ERRORS sec_login_s_no_current_context The caller does not have a valid network login context. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_site_open sec_rgy_site_bind 4 sec_rgy_site_bind_update NAME sec_rgy_site_bind_update - Binds to a registry update site SYNOPSIS #include void sec_rgy_site_bind_update( unsigned_char_t *site_name, sec_rgy_bind_auth_info_t *auth_info, sec_rgy_handle_t *context, error_status_t *status); PARAMETERS Input site_name A character string (type unsigned_char_t) containing the name of the registry site to bind to. Supply this name in any of the following forms: + To choose the update site to bind to in the named cell, specify a cell name (for example, /.../r_d.com or /.: for the local cell) + To start the search for the update site at a specific replica in the replica's cell, specify either the replica's global name (for example, /.../r_d.com/subsys/dce/sec/rs_server_250_2) or the replica's network address (for example, ncadg_ip_udp:15.22.144.248) auth_info A pointer to the sec_rgy_bind_auth_info_t structure that identifies the authentication protocol, protection level, and authorization protocol to use in establishing the binding. (See the rpc_binding_set_auth_info() routine). If the sec_rgy_bind_auth_info_t structure specifies authenticated rpc, the caller must have established a valid network identity for this call to succeed. Output context A pointer to a sec_rgy_handle_t variable. Upon return, this contains a registry server handle indicating ("bound to") the desired registry site. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_site_bind_update() routine binds to a registry update site. A registry update site is a master server that may control several satellite (query) servers. To change the registry database, it is necessary to change a registry update site, which then automatically updates its associated query sites. No changes can be made directly to a registry query database. The site_name parameter identifies either the cell in which to find the update site or the replica at which to start the search for the update site. If site_name is NULL, or a zero-length string, an update site in the local cell is selected by the client agent. The handle for the associated registry server is returned in context. The handle is to an update site. Use this registry context handle in subsequent calls that update or query the the registry database (for example, the sec_rgy_pgo_add() or sec_rgy_acct_lookup() call). FILES SYS$COMMON:[DCE$LIBRARY]BINDING.IDL The idl file from which dce/binding.h was derived. ERRORS sec_login_s_no_current_context The caller does not have a valid network login context. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_site_open sec_rgy_site_bind sec_rgy_site_open 4 sec_rgy_site_binding_get_info NAME sec_rgy_site_binding_get_info - Returns information from the registry binding handle SYNOPSIS #include void sec_rgy_site_binding_get_info( sec_rgy_handle_t context, unsigned_char_t **cell_name, unsigned_char_t **server_name, unsigned_char_t **string_binding, sec_rgy_bind_auth_info_t *auth_info, error_status_t *status); PARAMETERS Input context A sec_rgy_handle_t variable that contains a registry server handle indicating ("bound to") the desired registry site. To obtain information on the default binding handle, initialize context to sec_rgy_default_handle. A valid login context must be set for the process if context is set to sec_rgy_default_handle; otherwise the error sec_under_login_s_no_current_context is returned. Output cell_name The name of the home cell for this registry. server_name The name of the node on which the server is resident. This name is either a global name or a network address, depending on the form in which the name was input to the call that bound to the site. string_binding A string containing binding information from sec_rgy_handle_t. auth_info A pointer to the sec_rgy_bind_auth_info_t structure that identifies the authentication protocol, protection level, and authorization protocol to use in establishing the binding. (See the rpc_binding_set_auth_info() routine). status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_site_binding_get_info() routine returns the site name and authentication information associated with the context parameter. If the context is the default context, the information for the default binding is returned. Passing in a NULL value for any of the output values (except for status) will prevent that value from being returned. Memory is allocated for the string returned in the cell_name, server_name, and string_binding parameters. The application calls the rpc_string_free() routine to deallocate that memory. FILES SYS$COMMON:[DCE$LIBRARY]BINDING.IDL The idl file from which dce/binding.h was derived. ERRORS sec_under_login_s_no_current_context sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_site_open sec_rgy_site_bind 4 sec_rgy_site_close NAME sec_rgy_site_close - Frees the binding handle for a registry server SYNOPSIS #include void sec_rgy_site_close( sec_rgy_handle_t context, error_status_t *status); PARAMETERS Input context An opaque handle indicating ("bound to") a registry server. Use sec_rgy_site_open() to acquire a bound handle. Output status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_site_close() routine frees the memory occupied by the specified handle and destroys its binding with the registry server. NOTES A handle cannot be used after it is freed. FILES SYS$COMMON:[DCE$LIBRARY]BINDING.IDL The idl file from which dce/binding.h was derived. ERRORS error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_site_get sec_rgy_site_is_readonly sec_rgy_site_open sec_rgy_site_open_query sec_rgy_site_open_update 4 sec_rgy_site_get NAME sec_rgy_site_get - Returns the string representation for a bound registry site SYNOPSIS #include void sec_rgy_site_get( sec_rgy_handle_t context, unsigned_char_t **site_name, error_status_t *status); PARAMETERS Input context An opaque handle indicating (bound to'') a registry server. Use sec_rgy_site_open() to acquire a bound handle. To obtain information on the default binding handle, initialize context to sec_rgy_default_handle. A valid login context must be set for the process if context is set to sec_rgy_default_handle; otherwise the error sec_under_login_s_no_current_context is returned. Output site_name A pointer to a character string (type unsigned_char_t) containing the returned name of the registry site associated with context, the given registry server handle. The name is either a global name or a network address, depending on the form in which the name was input to the call that bound to the site. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_site_get() routine returns the name of the registry site associated with the specified handle. If the handle is the default context, the routine returns the name of the default context's site. Memory is allocated for the string returned in the site_name parameter. The application calls the rpc_string_free() routine to deallocate that memory. NOTES To obtain binding information, the use of the sec_rgy_site_binding_get_info() call is recommended in place of this call. FILES SYS$COMMON:[DCE$LIBRARY]BINDING.IDL The idl file from which dce/binding.h was derived. ERRORS sec_under_login_s_no_current_context sec_rgy_server_unavailable The requested registry server is not available. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_site_open 4 sec_rgy_site_is_readonly NAME sec_rgy_site_is_readonly - Checks whether a registry site is read-only SYNOPSIS #include boolean32 sec_rgy_site_is_readonly( sec_rgy_handle_t context); PARAMETERS Input context An opaque handle indicating (bound to'') a registry server. Use sec_rgy_site_open() to acquire a bound handle. DESCRIPTION The sec_rgy_site_is_readonly() routine checks whether the registry site associated with the specified handle is a query site or an update site. A query site is a read-only replica of a master registry database. The update site accepts changes to the registry database, and duplicates the changes in its associated query sites. RETURN VALUES The routine returns: + TRUE if the registry site is read-only or if there was an error using the specified handle + FALSE if the registry site is an update site FILES SYS$COMMON:[DCE$LIBRARY]BINDING.IDL The idl file from which dce/binding.h was derived. RELATED INFORMATION Functions: sec_intro sec_rgy_site_open sec_rgy_site_open_query 4 sec_rgy_site_open NAME sec_rgy_site_open - Binds to a registry site SYNOPSIS #include void sec_rgy_site_open( unsigned_char_t *site_name, sec_rgy_handle_t *context, error_status_t *status); PARAMETERS Input site_name A pointer to a character string (type unsigned_char_t) containing the name of the registry site to bind to. Supply this name in any of the following forms: + To randomly choose a site to bind to in the named cell, specify a cell name (for example, /.../r_d.com or /.: for the local cell) + To bind to a specific site in a specific cell, specify either the site's global name (for example, /.../r_d.com/subsys/dce/sec/rs_server_250_2) or the site's network address (for example, ncadg_ip_udp:15.22.144.248) Note that if you specify the name of a specific secd to bind to and the name is not valid, the call will bind to a random site in the cell if the specified cell name is valid. Output context A pointer to a sec_rgy_handle_t variable. Upon return, this contains a registry server handle indicating ("bound to") the desired registry site. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_site_open() routine binds to a registry site at the level of security specified in the rpc_binding_set_auth_info() call. The site_name parameter identifies the registry to use. If site_name is NULL, or a zero-length string, a registry site in the local cell is selected by the client agent. The caller must have established a valid network identity for this call to succeed. NOTES To bind to a registry site, the use of the sec_rgy_site_bind() call is recommended in place of this call. Like sec_rgy_site_open_query() routine, this routine binds arbitrarily to either an update or query site. Although update sites can accept queries, query sites cannot accept updates. To specifically select an update site, use sec_rgy_site_open_update(). FILES SYS$COMMON:[DCE$LIBRARY]BINDING.IDL The idl file from which dce/binding.h was derived. ERRORS sec_login_s_no_current_context The caller does not have a valid network login context. sec_rgy_server_unavailable The requested registry server is not available. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_site_close sec_rgy_site_is_readonly sec_rgy_site_open_query sec_rgy_site_open_update 4 sec_rgy_site_open_query NAME sec_rgy_site_open_query - Binds to a registry query site SYNOPSIS #include void sec_rgy_site_open_query( unsigned_char_t *site_name, sec_rgy_handle_t *context, error_status_t *status); PARAMETERS Input site_name A character string (type unsigned_char_t) containing the name of the registry query site to bind to. Supply this name in any of the following forms: + To randomly choose a site to bind to in the named cell, specify a cell name (for example, /.../r_d.com or /.: for the local cell) + To bind to a specific site in a specific cell, specify either the site's global name (for example, /.../r_d.com/subsys/dce/sec/rs_server_250_2) or the site's network address (for example, ncadg_ip_udp:15.22.144.248) Output context A pointer to a sec_rgy_handle_t variable. Upon return, this contains a registry server handle indicating ("bound to") the desired registry site. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_site_open_query() routine binds to a registry query site. A registry query site is a satellite server that operates on a periodically updated copy of the main registry database. To change the registry database, it is necessary to change a registry update site, which then automatically updates its associated query sites. No changes can be made directly to a registry query database. The site_name parameter identifies the query site to use. If site_name is NULL, or a zero-length string, a query site in the local cell is selected by the client agent. The handle for the associated registry server is returned in context. The caller must have established a valid network identity for this call to succeed. NOTES To bind to a registry query site, the use of the sec_rgy_site_bind_query() call is recommended in place of this call. Like sec_rgy_site_open() routine, this routine binds arbitrarily to either an update or query site. Although update sites can accept queries, query sites cannot accept updates. To specifically select an update site, use sec_rgy_site_open_update(). FILES SYS$COMMON:[DCE$LIBRARY]BINDING.IDL The idl file from which dce/binding.h was derived. Errors sec_login_s_no_current_context The caller does not have a valid network login context. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_site_close sec_rgy_site_get sec_rgy_site_is_readonly sec_rgy_site_open sec_rgy_site_open_update 4 sec_rgy_site_open_update NAME sec_rgy_site_open_update - Binds to a registry update site SYNOPSIS #include void sec_rgy_site_open_update( unsigned_char_t *site_name, sec_rgy_handle_t *context, error_status_t *status); PARAMETERS Input site_name A character string (type unsigned_char_t) containing the name of an update registry site to bind to. Supply this name in any of the following forms: + To choose the update site to bind to in the named cell, specify a cell name (for example, /.../r_d.com or /.: for the local cell) + To start the search for the update site at a specific replica in the replica's cell, specify either the site's global name (for example, /.../r_d.com/subsys/dce/sec/rs_server_250_2) or the site's network address (for example, ncadg_ip_udp:15.22.144.248) Output context A pointer to a sec_rgy_handle_t variable. Upon return, this contains a registry server handle indicating ("bound to") the desired registry site. status A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_site_open_update() routine binds to a registry update site. A registry update site is a master server that may control several satellite (query) servers. To change the registry database, it is necessary to change a registry update site, which then automatically updates its associated query sites. No changes can be made directly to a registry query database. The site_name parameter identifies either the cell in which to find the update site or the replica at which to start the search for the update site. If site_name is NULL, or a zero-length string, an update site in the local cell is selected by the client agent. The handle for the associated registry server is returned in context. The handle is to an update site. Use this registry context handle in subsequent calls that update or query the the registry database (for example, the sec_rgy_pgo_add() or sec_rgy_acct_lookup() call). The caller must have established a valid network identity for this call to succeed. NOTES To bind to a registry update site, the use of the sec_rgy_site_bind_update() call is recommended in place of this call. FILES SYS$COMMON:[DCE$LIBRARY]BINDING.IDL The idl file from which dce/binding.h was derived. ERRORS sec_login_s_no_current_context The caller does not have a valid network login context. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro sec_rgy_site_close sec_rgy_site_get sec_rgy_site_is_readonly sec_rgy_site_open sec_rgy_site_open_query 4 sec_rgy_unix_getgrgid NAME sec_rgy_unix_getgrgid - Returns a UNIX style group entry for the account matching the specified group ID SYNOPSIS #include void sec_rgy_unix_getgrent( sec_rgy_handle_t context, signed32 gid, signed32 max_number, sec_rgy_cursor_t *item_cursor, sec_rgy_unix_group_t *group_entry, signed32 *number_members, sec_rgy_member_t member_list[], error_status_t *status); PARAMETERS Input A pointer to an opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. gid A 32-bit integer specifying the group ID to match. max_number The maximum number of members to be returned by the call. This must be no larger than the allocated size of the member_list[] array. Input/Output item_cursor An opaque pointer indicating a specific PGO item entry in the registry database. The sec_rgy_pgo_get_next() routine returns the PGO item indicated by item_cursor, and advances the cursor to point to the next item in the database. When the end of the list of entries is reached, the routine returns sec_rgy_no_more_entries. Use sec_rgy_cursor_reset() to refresh the cursor. Output group_entry A UNIX style group entry structure returned with information about the account matching gid. number_members An signed 32-bit integer containing the total number of member names returned in the member_list[] array. member_list[] An array of character strings to receive the returned member names. The size allocated for the array is given by max_number. If this value is less than the total number of members in the membership list, multiple calls must be made to return all of the members. status On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_unix_getgrgid() routine returns the next UNIX group structure that matches the input UNIX group ID. The structure is in the following form: typedef struct { sec_rgy_name_t name; signed32 gid; sec_rgy_member_buf_t members; } sec_rgy_unix_group_t; The structure includes o The name of the group. o The group's UNIX ID. o A string containing the names of the group members. This string is limited in size by the size of the sec_rgy_member_buf_t type defined in rgynbase.idl. The routine also returns an array of member names, limited in size by the number_members parameter. This call is supplied in source code form. FILES SYS$COMMON:[DCE$LIBRARY]RGYBASE.IDL The idl file from which dce/rgybase.h was derived. ERRORS sec_rgy_nomore_entries The end of the list of entries has been reached. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro. 4 sec_rgy_unix_getgrnam NAME sec_rgy_unix_getgrnam - Returns a UNIX style group entry for the account matching the specified group name SYNOPSIS #include void sec_rgy_unix_getgrnam( sec_rgy_handle_t context, sec_rgy_name_t name, signed32 name_length, signed32 max_num_members, sec_rgy_cursor_t item_cursor, sec_rgy_unix_group_t group_entry, signed32 number_members, sec_rgy_member_t member_list[], error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. name A character string (of type sec_rgy_name_t) specifying the group name to be matched. name_length An signed 32-bit integer specifying the length of name in characters. max_num_members The maximum number of members to be returned by the call. This must be no larger than the allocated size of the member_list[] array. Input/Output item_cursor An opaque pointer indicating a specific PGO item entry in the registry database. The sec_rgy_unix_getgrnam() routine returns the PGO item indicated by item_cursor, and advances the cursor to point to the next item in the database. When the end of the list of entries is reached, the routine returns sec_rgy_no_more_entries. Use sec_rgy_cursor_reset() to refresh the cursor. Output group_entry A UNIX style group entry structure returned with information about the account matching name. number_members An signed 32-bit integer containing the total number of member names returned in the member_list[] array. member_list[] An array of character strings to receive the returned member names. The size allocated for the array is given by max_number. If this value is less than the total number of members in the membership list, multiple calls must be made to return all of the members. status On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_unix_getgrnam() routine looks up the next group entry in the registry that matches the input group name and returns the corresponding UNIX style group structure. The structure is in the following form: typedef struct { sec_rgy_name_t name; signed32 gid; sec_rgy_member_buf_t members; } sec_rgy_unix_group_t; The structure includes + The name of the group. + The group's UNIX ID. + A string containing the names of the group members. This string is limited in size by the size of the sec_rgy_member_buf_t type defined in rgynbase.idl. The routine also returns an array of member names, limited in size by the number_members parameter. Note that the array contains only the names explicitly specified as members of the group. A principal that was made a member of the group because that group was assigned as the principal's primary group will not appear in the array. This call is provided in source code form. FILES SYS$COMMON:[DCE$LIBRARY]RGYBASE.IDL The idl file from which dce/rgybase.h was derived. ERRORS sec_rgy_no_more_entries The end of the list of entries has been reached. sec_rgy bad_data The name supplied as input was too long. error_status_ok The call was successful. sec_rgy_server_unavailable The DCE Registry Server is unavailable. RELATED INFORMATION Functions: sec_intro 4 sec_rgy_unix_getpwnam NAME sec_rgy_unix_getpwnam - Returns a UNIX style passwd entry for account matching the specified name. SYNOPSIS #include void sec_rgy_unix_getpwnam ( sec_rgy_handle_t context, sec_rgy_name_t name, unsigned32 name_len, sec_rgy_cursor_t *item_cursor, sec_rgy_unix_passwd_t *passwd_entry, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open to acquire a bound handle. name A character string (of type sec_rgy_name_t) containing the name of the person, group, or organization whose name entry is desired. name_len A 32-bit integer representing the length of the name in characters. Input/Output item_cursor An opaque pointer indicating a specific PGO item entry in the registry database. The sec_rgy_unix_getpwnam routine returns the PGO item indicated by item_cursor, and advances the cursor to point to the next item in the database. When the end of the list of entries is reached, the routine returns sec_rgy_no_more_entries. Use sec_rgy_cursor_reset to refresh the cursor. Output passwd_entry A UNIX style passwd structure returned with information about the account matching name. status On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_unix_getpwnam routine returns the next UNIX passwd structure that matches the input name. The structure is in the form: typedef struct { sec_rgy_unix_login_name_t name; sec_rgy_unix_passwd_buf_t passwd; signed32 uid; signed32 gid; signed32 oid; sec_rgy_unix_gecos_t gecos; sec_rgy_pname_t homedir; sec_rgy_pname_t shell; } sec_rgy_unix_passwd_t; The structure includes: + The account's login name. + The account's password. + The account's UNIX ID. + The UNIX ID of group and organization associated with the account. + The account's GECOS information. + The account's home directory. + The account's login shell This call is provided in source code form. FILES SYS$COMMON:[DCE$LIBRARY]RGYNBASE.IDL The idl file from which rgynbase.h was derived. ERRORS sec_rgy bad_data The name supplied as input was too long. error_status_ok The call was successful. sec_rgy_no_more_entries The end of the list of entries has been reached. RELATED INFORMATION Functions: sec_intro 4 sec_rgy_unix_getpwuid NAME sec_rgy_unix_getpwuid - Returns a UNIX style passwd entry for the account matching the specified UID SYNOPSIS #include void sec_rgy_unix_getpwuid( sec_rgy_handle_t context, signed32 uid, sec_rgy_cursor_t *item_cursor, sec_rgy_unix_passwd_t *passwd_entry, error_status_t *status); PARAMETERS Input context An opaque handle bound to a registry server. Use sec_rgy_site_open() to acquire a bound handle. uid A 32-bit integer UNIX ID. Input/Output item_cursor An opaque pointer indicating a specific PGO item entry in the registry database. The sec_rgy_unix_getpwuid() routine returns the PGO item indicated by item_cursor, and advances the cursor to point to the next item in the database. When the end of the list of entries is reached, the routine returns sec_rgy_no_more_entries. Use sec_rgy_cursor_reset() to refresh the cursor. Output passwd_entry A UNIX style password structure returned with information about the account matching uid. status On successful completion, the routine returns error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_unix_getpwuid() routine looks up the next passwd entry in the registry that matches the input UNIX ID and returns the corresponding sec_rgy_passwd structure. The structure is in the following form: typedef struct { sec_rgy_unix_login_name_t name; sec_rgy_unix_passwd_buf_t passwd; signed32 Vuid; signed32 Vgid; signed32 oid; sec_rgy_unix_gecos_t gecos; sec_rgy_pname_t homedir; sec_rgy_pname_t shell; } sec_rgy_unix_passwd_t; The structure includes + The account's login name. + The account's password. + The account's UNIX ID. + The UNIX ID of group and organization associated with the account. + The account's GECOS information. + The account's home directory. + The account's login shell FILES SYS$COMMON:[DCE$LIBRARY]RGYNBASE.IDL The idl file from which dce/rgynbase.h was derived. This call is provided in source code form. ERRORS sec_rgy_no_more_entries The end of the list of entries has been reached. sec_rgy_server_unavailable The DCE Registry Server is unavailable. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro 4 sec_rgy_wait_until_consistent NAME sec_rgy_wait_until_consistent - Blocks the caller while prior updates are propagated to the registry replicas SYNOPSIS #include boolean32 sec_rgy_wait_until_consistent( sec_rgy_handle_t context, error_status_t *status); PARAMETERS Input context The registry server handle associated with the master registry. Output status A pointer to the completion status. On successful completion, status is assigned error_status_ok. Otherwise, it returns an error. DESCRIPTION The sec_rgy_wait_until_consistent() routine blocks callers until all prior updates to the master registry have been propagated to all active registry replicas. RETURN VALUES The routine returns TRUE when all active replicas have received the prior updates. It returns FALSE if at least one replica did not receive the updates. FILES SYS$COMMON:[DCE$LIBRARY]MISC.IDL The idl file from which dce/misc.h was derived. ERRORS sec_rgy_server_unavailable The server for the master registry is not available. sec_rgy_read_only Either the master site is in maintenance mode or the site associated with the handle is a read-only (query) site. error_status_ok The call was successful. RELATED INFORMATION Functions: sec_intro 2 DCE_DTS DCE Distributed Time Service (DTS) synchronizes the clocks in a networked system. It provides the following facilities: + The dtsd daemon + The DTS control program (dtscp) + The DTS local clock setting program (dtsdate) The DTS is implemented in the dtsd process. Both clerks and servers use the same daemon. The behavior of the dtsd daemon is determined by the dtscp command. Invocation of dtsd leaves it in an idle state. In order for it to assume an identity, it must be "created" with the dtscp create command. After the DTS entity is created, it is still in a non-functioning state. To put it into operation, you must invoke dtscp enable, which causes an immediate synchronization to take place. For more information, see the enable reference page in this chapter. To bring down a DTS entity, you must first stop it with dtscp disable and then delete it with dtscp delete. For more information, see the disable and delete reference pages in this chapter. The dtsdate command sets the local clock of a system to be the same as the host remote_host, running a dtsd server. For more information see the dtsdate reference page in this chapter. Books: DCE Administration Guide DCE Administration Reference 3 Application_Routines NAME dts_intro - Introduction to DCE Distributed Time Service (DTS) DESCRIPTION The DCE Distributed Time Service programming routines can obtain time- stamps that are based on Coordinated Universal Time (UTC), translate between different timestamp formats, and perform calculations on time- stamps. Applications can call the DTS routines from server or clerk systems and use the timestamps that DTS supplies to determine event sequencing, duration, and scheduling. The DTS routines can perform the following basic functions: + Retrieve the current (UTC-based) time from DTS. + Convert binary timestamps expressed in the utc time structure to or from tm structure components. + Convert the binary timestamps expressed in the utc time structure to or from timespec structure components. + Convert the binary timestamps expressed in the utc time structure to or from ASCII strings. + Compare two binary time values. + Calculate binary time values. + Obtain time zone information. DTS can convert between several types of binary time structures that are based on different calendars and time unit measurements. DTS uses UTC-based time structures, and can convert other types of time structures to its own presentation of UTC-based time. Absolute time is an interval on a time scale; absolute time measurements are derived from system clocks or external time-providers. For DTS, absolute times reference the UTC standard and include the inaccuracy and other information. When you display an absolute time, DTS converts the time to ASCII text, as shown in the following display: 1992-11-21-13:30:25.785-04:00I000.082 Relative time is a discrete time interval that is often added to or sub- tracted from an absolute time. A TDF associated with an absolute time is one example of a relative time. Note that a relative time does not use the calendar date fields, since these fields concern absolute time. Coordinated Universal Time (UTC) is the international time standard that DTS uses. The zero hour of UTC is based on the zero hour of Greenwich Mean Time (GMT). The documentation consistently refers to the time zone of the Greenwich Meridian as GMT. However, this time zone is also some- times referred to as UTC. The Time Differential Factor (TDF) is the difference between UTC and the time in a particular time zone. The user's environment determines the time zone rule (details are system dependent). If the user's environment does not specify a time zone rule, the system's rule is used (details of the rule are system dependent). For example, on OpenVMS systems, the rule pointed to by the filename in SYS$SYSTEM:SYS$TIMEZONE_SRC.DAT applies. The OSF DCE Application Development Guide provides additional infor- mation about UTC and GMT, TDF and time zones, and relative and absolute times. Unless otherwise specified, the default input and output parameters are as follows: + If NULL is specified for a utc input parameter, the current time is used. + If NULL is specified for any output parameter, no result is returned. RELATED INFORMATION Books: OSF DCE Application Development Guide 4 List_of_all_routines An alphabetical listing of the DTS portable interface routines and a brief description of each one follows: utc_abstime() Computes the absolute value of a relative binary timestamp. utc_addtime() Computes the sum of two binary timestamps; the timestamps can be two relative times or a relative time and an absolute time. utc_anytime() Converts a binary timestamp to a tm structure by using the TDF information contained in the timestamp to determine the TDF returned with the tm structure. utc_anyzone() Gets the time zone label and offset from GMT by using the TDF contained in the utc input parameter. utc_ascanytime() Converts a binary timestamp to an ASCII string that represents an arbitrary time zone. utc_ascgmtime() Converts a binary timestamp to an ASCII string that expresses a GMT time. utc_asclocaltime() Converts a binary timestamp to an ASCII string that represents a local time. utc_ascreltime() Converts a relative binary timestamp to an ASCII string that represents the time. utc_binreltime() Converts a relative binary timestamp to two timespec structures that express relative time and inaccuracy. utc_bintime() Converts a binary timestamp to a timespec structure. utc_boundtime() Given two UTC times, one before and one after an event, returns a single UTC time whose inaccuracy includes the event. utc_cmpintervaltime() Compares two binary timestamps or two relative binary timestamps. utc_cmpmidtime() Compares two binary timestamps or two relative binary timestamps, ignoring inaccuracies. utc_gettime() Returns the current system time and inaccuracy as a binary timestamp. utc_getusertime() Returns the time and process-specific TDF, rather than the system-specific TDF. utc_gmtime() Converts a binary timestamp to a tm structure that expresses GMT or the equivalent UTC. utc_gmtzone() Gets the time zone label for GMT. utc_localtime() Converts a binary timestamp to a tm structure that expresses local time. utc_localzone() Gets the local time zone label and offset from GMT, given utc. utc_mkanytime() Converts a tm structure and TDF (expressing the time in an arbitrary time zone) to a binary timestamp. utc_mkascreltime() Converts a NULL-terminated character string that represents a relative timestamp to a binary timestamp. utc_mkasctime() Converts a NULL-terminated character string that represents an absolute timestamp to a binary timestamp. utc_mkbinreltime() Converts a timespec structure expressing a relative time to a binary timestamp. utc_mkbintime() Converts a timespec structure to a binary timestamp. utc_mkgmtime() Converts a tm structure that expresses GMT or UTC to a binary timestamp. utc_mklocaltime() Converts a tm structure that expresses local time to a binary timestamp. utc_mkreltime() Converts a tm structure that expresses relative time to a relative binary timestamp. utc_mulftime() Multiplies a relative binary timestamp by a floating-point value. utc_multime() Multiplies a relative binary timestamp by an integer factor. utc_pointtime() Converts a binary timestamp to three binary timestamps that represent the earliest, most likely, and latest time. utc_reltime() Converts a relative binary timestamp to a tm structure. utc_spantime() Given two (possibly unordered) binary timestamps, returns a single UTC time interval whose inaccuracy spans the two input binary timestamps. utc_subtime() Computes the difference between two binary timestamps that express either an absolute time and a relative time, two relative times, or two absolute times. 4 utc_abstime NAME utc_abstime - Computes the absolute value of a relative binary timestamp SYNOPSIS #include int utc_abstime( utc_t* result, utc_t *utc ); PARAMETERS Input utc Relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output result Absolute value of the input relative binary timestamp. DESCRIPTION The utc_abstime() routine computes the absolute value of a relative binary timestamp. The input timestamp represents a relative (delta) time. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid results. EXAMPLES The following example scales a relative time, computes its absolute value, and prints the result. utc_t relutc, scaledutc; char timstr[UTC_MAX_STR_LEN]; /* Make sure relative timestamp represents a positive interval... */ utc_abstime(&relutc, /* Out: Abs-value of rel time */ &relutc); /* In: Relative time to scale */ /* Scale it by a factor of 17... */ utc_multime(&scaledutc, /* Out: Scaled relative time */ &relutc, /* In: Relative time to scale */ 17L); /* In: Scale factor */ utc_ascreltime(timstr, /* Out: ASCII relative time */ UTC_MAX_STR_LEN, /* In: Length of input string */ &scaledutc); /* In: Relative time to */ /* convert */ printf("%s\n",timstr); /* Scale it by a factor of 17.65... */ utc_mulftime(&scaledutc, /* Out: Scaled relative time */ &relutc, /* In: Relative time to scale */ 17.65); /* In: Scale factor */ utc_ascreltime(timstr, /* Out: ASCII relative time */ UTC_MAX_STR_LEN, /* In: Length of input string */ &scaledutc); /* In: Relative time to */ /* convert */ printf("%s\n",timstr); 4 utc_addtime NAME utc_addtime - Computes the sum of two binary timestamps SYNOPSIS #include int utc_addtime( utc_t* result, utc_t *utc1, utc_t *utc2 ); PARAMETERS Input utc1 Binary timestamp or relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. utc2 Binary timestamp or relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output result Resulting binary timestamp or relative binary timestamp, depending upon the operation performed: + relative time+relative time=relative time + absolute time+relative time=absolute time + relative time+absolute time=absolute time + absolute time+absolute time is undefined. (See the note later in this reference page.) DESCRIPTION The utc_addtime() routine adds two binary timestamps, producing a third binary timestamp whose inaccuracy is the sum of the two input inaccuracies. One or both of the input timestamps typically represents a relative (delta) time. The TDF in the first input time- stamp is copied to the output. The timestamps can be two relative times or a relative time and an absolute time. NOTES Although no error is returned, the combination absolute time+absolute time should not be used. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid results. EXAMPLES The following example shows how to compute a timestamp that represents a time at least 5 seconds in the future. utc_t now, future, fivesec; reltimespec_t tfivesec; timespec_t tzero; /* Construct a timestamp that represents 5 seconds... */ tfivesec.tv_sec = 5; tfivesec.tv_nsec = 0; tzero.tv_sec = 0; tzero.tv_nsec = 0; utc_mkbinreltime(&fivesec, /* Out: 5 secs in binary timestamp */ &tfivesec, /* In: 5 secs in timespec */ &tzero); /* In: 0 secs inaccuracy in timespec */ /* Get the maximum possible current time... * (The NULL input parameter is used to specify the current time.) */ utc_pointtime((utc_t *)0, /* Out: Earliest possible current time */ (utc_t *)0, /* Out: Midpoint of current time */ &now, /* Out: Latest possible current time */ (utc_t *)0); /* In: Use current time */ /* Add 5 seconds to get future timestamp... */ utc_addtime(&future, /* Out: Future binary timestamp */ &now, /* In: Latest possible time now */ &fivesec); /* In: 5 secs */ RELATED INFORMATION Functions: utc_subtime 4 utc_anytime NAME utc_anytime - Converts a binary timestamp to a tm structure SYNOPSIS #include int utc_anytime( struct tm *timetm, long *tns, struct tm *inacctm, long *ins, long *tdf, utc_t *utc ); PARAMETERS Input utc Binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output timetm Time component of the binary timestamp expressed in the timestamp's local time. tns Nanoseconds since the Time component of the binary timestamp. inacctm Seconds of the inaccuracy component of the binary timestamp.If the inaccuracy is finite, then tm_mday returns a value of -1 and tm_mon and tm_year return values of 0 (zero). The field tm_yday contains the inaccuracy in days. If the inaccuracy is unspecified, all tm structure fields return values of -1. ins Nanoseconds of the inaccuracy component of the binary timestamp. tdf TDF component of the binary timestamp in units of seconds east of GMT. DESCRIPTION The utc_anytime() routine converts a binary timestamp to a tm structure by using the TDF information contained in the timestamp to determine the TDF returned with the tm structure. The TDF information contained in the timestamp is returned with the time and inaccuracy components; the TDF component determines the offset from GMT and the local time value of the tm structure. Additional returns include nanoseconds since Time and nanoseconds of inaccuracy. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES The following example converts a timestamp by using the TDF information in the timestamp, and then prints the result. utc_t evnt; struct tm tmevnt; timespec_t tevnt, ievnt; char tznam[80]; /* Assume evnt contains the timestamp to convert... * * Get time as a tm structure, using the time zone information * in the timestamp... */ utc_anytime(&tmevnt, /* Out: tm struct of time of evnt */ (long *)0, /* Out: nanosec of time of evnt */ (struct tm *)0, /* Out: tm struct of inacc of evnt */ (long *)0, /* Out: nanosec of inacc of evnt */ (int *)0, /* Out: tdf of evnt */ &evnt); /* In: binary timestamp of evnt */ /* Get the time and inaccuracy as timespec structures... */ utc_bintime(&tevnt, /* Out: timespec of time of evnt */ &ievnt, /* Out: timespec of inacc of evnt */ (int *)0, /* Out: tdf of evnt */ &evnt); /* In: Binary timestamp of evnt */ /* Construct the time zone name from time zone information in * the timestamp... */ utc_anyzone(tznam, /* Out: Time zone name */ 80, /* In: Size of time zone name */ (long *)0, /* Out: tdf of event */ (long *)0, /* Out: Daylight saving flag */ &evnt); /* In: Binary timestamp of evnt */ /* Print timestamp in the format: * * 1991-03-05-21:27:50.023I0.140 (GMT-5:00) * 1992-04-02-12:37:24.003Iinf (GMT+7:00) */ printf("%d-%02d-%02d-%02d:%02d:%02d.%03d", tmevnt.tm_year+1900, tmevnt.tm_mon+1, tmevnt.tm_mday, tmevnt.tm_hour, tmevnt.tm_min, tmevnt.tm_sec, (tevnt.tv_nsec/1000000)); if ((long)ievnt.tv_sec == -1) printf("Iinf"); else printf("I%d.%03d", ievnt.tv_sec, (ievnt.tv_nsec/1000000)); printf(" (%s)\n", tznam); RELATED INFORMATION Functions: utc_mkanytime utc_anyzone utc_gettime utc_getusertime utc_gmtime utc_localtime 4 utc_anyzone NAME utc_anyzone - Gets the time zone label and offset from GMT SYNOPSIS #include int utc_anyzone( char *tzname, size_t tzlen, long *tdf, int *isdst, const utc_t *utc ); PARAMETERS Input tzlen Length of the tzname buffer. utc Binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output tzname Character string that is long enough to hold the time zone label. tdf Longword with differential in seconds east of GMT. isdst Integer with a value of -1, indicating that no information is supplied as to whether it is standard time or daylight saving time. A value of -1 is always returned. DESCRIPTION The utc_anyzone() routine gets the time zone label and offset from GMT by using the TDF contained in the utc input parameter. The label returned is always of the form GMT+n or GMT-n where n is the tdf expressed in hours:minutes. (The label associated with an arbitrary time zone is not known; only the offset is known.) NOTES All of the output parameters are optional. No value is returned and no error occurs if the pointer is NULL. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or an insufficient buffer. EXAMPLES See the sample program in the utc_anytime reference page. RELATED INFORMATION Functions: utc_anytime utc_gmtzone utc_localzone 4 utc_ascanytime NAME utc_ascanytime - Converts a binary timestamp to an ASCII string that represents an arbitrary time zone SYNOPSIS #include int utc_ascanytime( char *cp, size_t stringlen, utc_t *utc ); PARAMETERS Input stringlen The length of the cp buffer. utc Binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output cp ASCII string that represents the time. DESCRIPTION The utc_ascanytime() routine converts a binary timestamp to an ASCII string that expresses a time. The TDF component in the timestamp determines the local time used in the conversion. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid results. EXAMPLES The following example converts a time to an ASCII string that expresses the time in the time zone where the timestamp was generated. utc_t evnt; char localTime[UTC_MAX_STR_LEN]; /* * Assuming that evnt contains the timestamp to convert, * convert the time to ASCII in the following format: * * 1991-04-01-12:27:38.37-8:00I2.00 */ utc_ascanytime(localtime, /* Out: Converted time */ UTC_MAX_STR_LEN, /* In: Length of string */ &evnt); /* In: Time to convert */ RELATED INFORMATION Functions: utc_ascgmtime utc_asclocaltime 4 utc_ascgmtime NAME utc_ascgmtime - Converts a binary timestamp to an ASCII string that expresses a GMT time SYNOPSIS #include int utc_ascgmtime( char *cp, size_t stringlen, utc_t *utc ); PARAMETERS Input stringlen Length of the cp buffer. utc Binary timestamp. Output cp ASCII string that represents the time. DESCRIPTION The utc_ascgmtime() routine converts a binary timestamp to an ASCII string that expresses a time in GMT. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid results. EXAMPLES The following example converts the current time to GMT format. char gmTime[UTC_MAX_STR_LEN]; /* Convert the current time to ASCII in the following format: * 1991-04-01-12:27:38.37I2.00 */ utc_ascgmtime(gmTime, /* Out: Converted time */ UTC_MAX_STR_LEN, /* In: Length of string */ (utc_t*) NULL); /* In: Time to convert */ /* Default is current time */ RELATED INFORMATION Functions: utc_ascanytime utc_asclocaltime 4 utc_asclocaltime NAME utc_asclocaltime - Converts a binary timestamp to an ASCII string that represents a local time SYNOPSIS #include int utc_asclocaltime( char *cp, size_t stringlen, utc_t *utc ); PARAMETERS Input stringlen Length of the cp buffer. utc Binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output cp ASCII string that represents the time. DESCRIPTION The utc_asclocaltime() routine converts a binary timestamp to an ASCII string that expresses local time. The user's environment determines the time zone rule (details are system dependent). If the user's environment does not specify a time zone rule, the system's rule is used (details of the rule are system dependent). For example, on OpenVMS systems, the rule pointed to by the filename in SYS$SYSTEM:SYS$TIMEZONE_SRC.DAT applies. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid results. EXAMPLES The following example converts the current time to local time. char localTime[UTC_MAX_STR_LEN]; /* Convert the current time... */ utc_asclocaltime(localTime, /* Out: Converted time */ UTC_MAX_STR_LEN, /* In: Length of string */ (utc_t*) NULL); /* In: Time to convert */ /* Default is current time */ RELATED INFORMATION Functions: utc_ascanytime utc_ascgmtime 4 utc_ascreltime NAME utc_ascreltime - Converts a relative binary timestamp to an ASCII string that represents the time SYNOPSIS #include int utc_ascreltime( char *cp, const size_t stringlen, utc_t *utc ); PARAMETERS Input utc Relative binary timestamp. stringlen Length of the cp buffer. Output cp ASCII string that represents the time. DESCRIPTION The utc_ascreltime() routine converts a relative binary timestamp to an ASCII string that represents the time. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid results. EXAMPLES See the sample program in the utc_abstime reference page. RELATED INFORMATION Functions: utc_mkascreltime 4 utc_binreltime NAME utc_binreltime - Converts a relative binary timestamp to two timespec structures that express relative time and inaccuracy SYNOPSIS #include int utc_binreltime( reltimespec_t *timesp, timespec_t *inaccsp, utc_t *utc ); PARAMETERS Input utc Relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output timesp Time component of the relative binary timestamp, in the form of seconds and nanoseconds since the base time (1970-01-01:00:00:00.0+00:00I0). inaccsp Inaccuracy component of the relative binary timestamp, in the form of seconds and nanoseconds. DESCRIPTION The utc_binreltime() routine converts a relative binary timestamp to two timespec structures that express relative time and inaccuracy. These timespec structures describe a time interval. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES The following example measures the duration of a process, then prints the resulting relative time and inaccuracy. utc_t before, duration; reltimespec_t tduration; timespec_t iduration; /* Get the time before the start of the operation... */ utc_gettime(&before); /* Out: Before binary timestamp */ /* ...Later... * Subtract, getting the duration as a relative time. * * NOTE: The NULL argument is used to obtain the current time. */ utc_subtime(&duration, /* Out: Duration rel bin timestamp */ (utc_t *)0, /* In: After binary timestamp */ &before); /* In: Before binary timestamp */ /* Convert the relative times to timespec structures... */ utc_binreltime(&tduration, /* Out: Duration time timespec */ &iduration, /* Out: Duration inacc timespec */ &duration); /* In: Duration rel bin timestamp */ /* Print the duration... */ printf("%d.%04d", tduration.tv_sec, (tduration.tv_nsec/10000)); if ((long)iduration.tv_sec == -1) printf("Iinf\n"); else printf( "I%d.%04d\n", iduration.tv_sec, (iduration.tv_nsec/100000) ); RELATED INFORMATION Functions: utc_mkbinreltime 4 utc_bintime NAME utc_bintime - Converts a binary timestamp to a timespec structure SYNOPSIS #include int utc_bintime( timespec_t *timesp, timespec_t *inaccsp, long *tdf, utc_t *utc ); PARAMETERS Input utc Binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output timesp Time component of the binary timestamp, in the form of seconds and nanoseconds since the base time. inaccsp Inaccuracy component of the binary timestamp, in the form of seconds and nanoseconds. tdf TDF component of the binary timestamp in the form of signed number of seconds east of GMT. DESCRIPTION The utc_bintime() routine converts a binary timestamp to a timespec structure. The TDF information contained in the timestamp is returned. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES See the sample program in the utc_anytime reference page. RELATED INFORMATION Functions: utc_binreltime utc_mkbintime 4 utc_boundtime NAME utc_boundtime - Given two UTC times, one before and one after an event, returns a single UTC time whose inaccuracy includes the event SYNOPSIS #include int utc_boundtime( utc_t *result, utc_t *utc1, utc_t *utc2 ); PARAMETERS Input utc1 Before binary timestamp or relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. utc2 After binary timestamp or relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output result Spanning timestamp. DESCRIPTION Given two UTC times, the utc_boundtime() routine returns a single UTC time whose inaccuracy bounds the two input times. This is useful for timestamping events: the routine gets the utc values before and after the event, then calls utc_boundtime() to build a timestamp that includes the event. NOTES The TDF in the output UTC value is copied from the utc2 input parameter. If one or both input values have unspecified inaccuracies, the returned time value also has an unspecified inaccuracy and is the average of the two input values. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid parameter order. EXAMPLES The following example records the time of an event and constructs a single timestamp, which includes the time of the event. Note that the utc_getusertime() routine is called so the time zone information that is included in the timestamp references the user's environment rather than the system's default time zone. The user's environment determines the time zone rule (details are system dependent). If the user's environment does not specify a time zone rule, the system's rule is used (details of the rule are system dependent). For example, on OpenVMS systems, the rule pointed to by the filename in SYS$SYSTEM:SYS$TIMEZONE_SRC.DAT applies. utc_t before, after, evnt; /* Get the time before the event... */ utc_getusertime(&before); /* Out: Before binary timestamp */ /* Get the time after the event... */ utc_getusertime(&after); /* Out: After binary timestamp */ /* Construct a single timestamp that describes the time of the * event... */ utc_boundtime(&evnt, /* Out: Timestamp that bounds event */ &before, /* In: Before binary timestamp */ &after); /* In: After binary timestamp */ RELATED INFORMATION Functions: utc_gettime utc_pointtime utc_spantime 4 utc_cmpintervaltime NAME utc_cmpintervaltime - Compares two binary timestamps or two relative binary timestamps SYNOPSIS #include int utc_cmpintervaltime( enum utc_cmptype *relation, utc_t *utc1, utc_t *utc2 ); PARAMETERS Input utc1 Binary timestamp or relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. utc2 Binary timestamp or relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output relation Receives the result of the comparison of utc1:utc2 where the result is an enumerated type with one of the following values: + utc_equalTo + utc_lessThan + utc_greaterThan + utc_indeterminate DESCRIPTION The utc_cmpintervaltime() routine compares two binary timestamps and returns a flag indicating that the first time is greater than, less than, equal to, or overlapping with the second time. Two times overlap if the intervals (time - inaccuracy, time + inaccuracy) of the two times intersect. The input binary timestamps express two absolute or two relative times. Do not compare relative binary timestamps to absolute binary timestamps. If you do, no meaningful results and no errors are returned. The following routine does a temporal ordering of the time intervals. utc1 is utc_lessThan utc2 iff utc1.time + utc1.inacc < utc2.time - utc2.inacc utc1 is utc_greaterThan utc2 iff utc1.time - utc1.inacc > utc2.time + utc2.inacc utc1 utc_equalTo utc2 iff utc1.time == utc2.time and utc1.inacc == 0 and utc2.inacc == 0 utc1 is utc_indeterminate with respect to utc2 if the intervals overlap. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument. EXAMPLES The following example checks to see if the current time is definitely after 13:00 local time. struct tm tmtime, tmzero; enum utc_cmptype relation; utc_t testtime; /* Zero the tm structure for inaccuracy... */ memset(&tmzero, 0, sizeof(tmzero)); /* Get the current time, mapped to a tm structure... * * NOTE: The NULL argument is used to get the current time. */ utc_gmtime(&tmtime, /* Out: Current GMT time in tm struct */ (long *)0, /* Out: Nanoseconds of time */ (struct tm *)0,/* Out: Current inaccuracy in tm struct */ (long *)0, /* Out: Nanoseconds of inaccuracy */ (utc_t *)0); /* In: Current timestamp */ /* Alter the tm structure to correspond to 13:00 local time */ tmtime.tm_hour = 13; tmtime.tm_min = 0; tmtime.tm_sec = 0; /* Convert to a binary timestamp... */ utc_mkgmtime(&testtime, /* Out: Binary timestamp of 13:00 */ &tmtime, /* In: 1:00 PM in tm struct */ 0, /* In: Nanoseconds of time */ &tmzero, /* In: Zero inaccuracy in tm struct */ 0); /* In: Nanoseconds of inaccuracy */ /* Compare to the current time. Note the use of the NULL argument */ utc_cmpintervaltime(&relation, /* Out: Comparison relation */ (utc_t *)0, /* In: Current timestamp */ &testtime); /* In: 13:00 PM timestamp */ /* If it is not later - wait, print a message, etc. */ if (relation != utc_greaterThan) { /* * Note: It could be earlier than 13:00 local time or it * could be indeterminate. If indeterminate, for some * applications it might be worth waiting. */ } RELATED INFORMATION Functions: utc_cmpmidtime 4 utc_cmpmidtime NAME utc_cmpmidtime - Compares two binary timestamps or two relative binary timestamps, ignoring inaccuracies SYNOPSIS #include int utc_cmpmidtime( enum utc_cmptype *relation, utc_t *utc1, utc_t *utc2 ); PARAMETERS Input utc1 Binary timestamp or relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. utc2 Binary timestamp or relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output relation Result of the comparison of utc1:utc2 where the result is an enumerated type with one of the following values: + utc_equalTo + utc_lessThan + utc_greaterThan DESCRIPTION The utc_cmpmidtime() routine compares two binary timestamps and returns a flag indicating that the first timestamp is greater than, less than, or equal to the second timestamp. Inaccuracy information is ignored for this comparison; the input values are therefore equivalent to the midpoints of the time intervals described by the input binary timestamps. The input binary timestamps express two absolute or two relative times. Do not compare relative binary timestamps to absolute binary timestamps. If you do, no meaningful results and no errors are returned. The following routine does a lexical ordering on the time interval midpoints. utc1 is utc_lessThan utc2 iff utc1.time < utc2.time utc1 is utc_greaterThan utc2 iff utc1.time > utc2.time utc1 is utc_equalTo utc2 iff utc1.time == utc2.time RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument. EXAMPLES The following example checks if the current time (ignoring inaccuracies) is after 13:00 local time. struct tm tmtime, tmzero; enum utc_cmptype relation; utc_t testtime; /* Zero the tm structure for inaccuracy... */ memset(&tmzero, 0, sizeof(tmzero)); /* Get the current time, mapped to a tm structure... * * NOTE: The NULL argument is used to get the current * time. */ utc_localtime(&tmtime, /* Out: Current local time in tm struct */ (long *)0, /* Out: Nanoseconds of time */ (struct tm *)0,/* Out: Current inacc in tm struct */ (long *)0, /* Out: Nanoseconds of inaccuracy */ (utc_t *)0); /* In: Current timestamp */ /* Alter the tm structure to correspond to 13:00 local time. */ tmtime.tm_hour = 13; tmtime.tm_min = 0; tmtime.tm_sec = 0; /* Convert to a binary timestamp... */ utc_mklocaltime(&testtime, /* Out: Binary timestamp of 13:00 */ &tmtime, /* In: 13:00 in tm struct */ 0, /* In: Nanoseconds of time */ &tmzero, /* In: Zero inaccuracy in tm struct */ 0); /* In: Nanoseconds of inaccuracy */ /* Compare to the current time. Note the use of the NULL argument */ utc_cmpmidtime(&relation, /* Out: Comparison relation */ (utc_t *)0, /* In: Current timestamp */ &testtime); /* In: 13:00 local time timestamp */ /* If the time is not later - wait, print a message, etc. */ if (relation != utc_greaterThan) { /* It is not later then 13:00 local time. Note that * this depends on the setting of the user's environment. */ } RELATED INFORMATION Functions: utc_cmpintervaltime 4 utc_gettime NAME utc_gettime - Returns the current system time and inaccuracy as a binary timestamp SYNOPSIS #include int utc_gettime( utc_t *utc ); PARAMETERS Input None. Output utc System time as a binary timestamp. DESCRIPTION The utc_gettime() routine returns the current system time and inaccuracy in a binary timestamp. The routine takes the TDF from the operating system's kernel; the TDF is specified in a system- dependent manner. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Generic error that indicates the time service cannot be accessed. EXAMPLES See the sample program in the utc_binreltime reference page. 4 utc_getusertime NAME utc_getusertime - Returns the time and process-specific TDF, rather than the system-specific TDF SYNOPSIS #include int utc_getusertime( utc_t *utc ); PARAMETERS Input None. Output utc System time as a binary timestamp. DESCRIPTION The utc_getusertime() routine returns the system time and inaccuracy in a binary timestamp. The routine takes the TDF from the user's environment, which determines the time zone rule (details are system dependent). If the user environment does not specify a TDF, the system's TDF is used. The system's time zone rule is applied (details of the rule are system dependent). For example, on OpenVMS systems, the rule pointed to by the filename in SYS$SYSTEM:SYS$TIMEZONE_SRC.DAT applies. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Generic error that indicates the time service cannot be accessed. EXAMPLES See the sample program in the utc_boundtime reference page. RELATED INFORMATION Functions: utc_gettime 4 utc_gmtime NAME utc_gmtime - Converts a binary timestamp to a tm structure that expresses GMT or the equivalent UTC SYNOPSIS #include int utc_gmtime( struct tm *timetm, long *tns, struct tm *inacctm, long *ins, utc_t *utc ); PARAMETERS Input utc Binary timestamp to be converted to tm structure components. Use NULL if you want this routine to use the current time for this parameter. Output timetm Time component of the binary timestamp. tns Nanoseconds since the Time component of the binary timestamp. inacctm Seconds of the inaccuracy component of the binary timestamp. If the inaccuracy is finite, then tm_mday returns a value of -1 and tm_mon and tm_year return values of 0 (zero). The field tm_yday contains the inaccuracy in days. If the inaccuracy is unspecified, all tm structure fields return values of -1. ins Nanoseconds of the inaccuracy component of the binary timestamp. If the inaccuracy is unspecified, ins returns a value of -1. DESCRIPTION The utc_gmtime() routine converts a binary timestamp to a tm structure that expresses GMT (or the equivalent UTC). Additional returns include nanoseconds since Time and nanoseconds of inaccuracy. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES See the sample program in the utc_cmpintervaltime reference page. RELATED INFORMATION Functions: utc_anytime utc_gmtzone utc_localtime utc_mkgmtime 4 utc_gmtzone NAME utc_gmtzone - Gets the time zone label for GMT SYNOPSIS #include int utc_gmtzone( char *tzname, size_t tzlen, long *tdf, int *isdst, utc_t *utc ); PARAMETERS Input tzlen Length of buffer tzname. utc Binary timestamp. This parameter is ignored. Output tzname Character string long enough to hold the time zone label. tdf Longword with differential in seconds east of GMT. A value of 0 (zero) is always returned. isdst Integer with a value of 0 (zero), indicating that daylight saving time is not in effect. A value of 0 (zero) is always returned. DESCRIPTION The utc_gmtzone() routine gets the time zone label and zero offset from GMT. Outputs are always tdf=0 and tzname=GMT. This routine exists for symmetry with the utc_anyzone() and the utc_localzone() routines. Use NULL if you want this routine to use the current time for this parameter. NOTES All of the output parameters are optional. No value is returned and no error occurs if the tzname pointer is NULL. RETURN VALUES 0 Indicates that the routine executed successfully (always returned). EXAMPLES The following example prints out the current time in both local time and GMT time. utc_t now; struct tm tmlocal, tmgmt; long tzoffset; int tzdaylight; char tzlocal[80], tzgmt[80]; /* Get the current time once, so both conversions use the same * time... */ utc_gettime(&now); /* Convert to local time, using the process TZ environment * variable... */ utc_localtime(&tmlocal, /* Out: Local time tm structure */ (long *)0, /* Out: Nanosec of time */ (struct tm *)0,/* Out: Inaccuracy tm structure */ (long *)0, /* Out: Nanosec of inaccuracy */ (int *)0, /* Out: TDF of local time */ &now); /* In: Current timestamp (ignore) */ /* Get the local time zone name, offset from GMT, and current * daylight savings flag... */ utc_localzone(tzlocal, /* Out: Local time zone name */ 80, /* In: Length of loc time zone name */ &tzoffset, /* Out: Loc time zone offset in secs */ &tzdaylight,/* Out: Local time zone daylight flag */ &now); /* In: Current binary timestamp */ /* Convert to GMT... */ utc_gmtime(&tmgmt, /* Out: GMT tm structure */ (long *)0, /* Out: Nanoseconds of time */ (struct tm *)0, /* Out: Inaccuracy tm structure */ (long *)0, /* Out: Nanoseconds of inaccuracy */ &now); /* In: Current binary timestamp */ /* Get the GMT time zone name... */ utc_gmtzone(tzgmt, /* Out: GMT time zone name */ 80, /* In: Size of GMT time zone name */ (long *)0, /* Out: GMT time zone offset in secs */ (int *)0, /* Out: GMT time zone daylight flag */ &now); /* In: Current binary timestamp */ /* (ignore) */ /* Print out times and time zone information in the following * format: * * 12:00:37 (EDT) = 16:00:37 (GMT) * EDT is -240 minutes ahead of Greenwich Mean Time. * Daylight savings time is in effect. */ printf("%d:%02d:%02d (%s) = %d:%02d:%02d (%s)\n", tmlocal.tm_hour, tmlocal.tm_min, tmlocal.tm_sec, tzlocal, tmgmt.tm_hour, tmgmt.tm_min, tmgmt.tm_sec, tzgmt); printf( "%s is %d minutes ahead of Greenwich Mean Time\n", tzlocal, tzoffset/60 ); if (tzdaylight != 0) printf("Daylight savings time is in effect\n"); RELATED INFORMATION Functions: utc_anyzone utc_gmtime utc_localzone 4 utc_localtime NAME utc_localtime - Converts a binary timestamp to a tm structure that expresses local time SYNOPSIS #include int utc_localtime( struct tm *timetm, long *tns, struct tm *inacctm, long *ins, utc_t *utc ); PARAMETERS Input utc Binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output timetm Time component of the binary timestamp, expressing local time. tns Nanoseconds since the Time component of the binary timestamp. inacctm Seconds of the inaccuracy component of the binary timestamp. If the inaccuracy is finite, then tm_mday returns a value of -1 and tm_mon and tm_year return values of 0 (zero). The field tm_yday contains the inaccuracy in days. If the inaccuracy is unspecified, all tm structure fields return values of -1. ins Nanoseconds of the inaccuracy component of the binary timestamp. If the inaccuracy is unspecified, ins returns a value of -1. DESCRIPTION The utc_localtime() routine converts a binary timestamp to a tm structure that expresses local time. The user's environment determines the time zone rule (details are system dependent). If the user's environment does not specify a time zone rule, the system's rule is used (details of the rule are system dependent). For example, on OpenVMS systems, the rule pointed to by the filename in SYS$SYSTEM:SYS$TIMEZONE_SRC.DAT applies. Additional returns include nanoseconds since Time and nanoseconds of inaccuracy. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES See the sample program in the utc_gmtzone reference page. RELATED INFORMATION Functions: utc_anytime utc_gmtime utc_localzone utc_mklocaltime 4 utc_localzone NAME utc_localzone - Gets the local time zone label and offset from GMT, given utc SYNOPSIS #include int utc_localzone( char *tzname, size_t tzlen, long *tdf, int *isdst, utc_t *utc ); PARAMETERS Input tzlen Length of the tzname buffer. utc Binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output tzname Character string long enough to hold the time zone label. tdf Longword with differential in seconds east of GMT. isdst Integer with a value of 0 (zero) if standard time is in effect or a value of 1 if daylight saving time is in effect. DESCRIPTION The utc_localzone() routine gets the local time zone label and offset from GMT, given utc. The user's environment determines the time zone rule (details are system dependent). If the user's environment does not specify a time zone rule, the system's rule is used (details of the rule are system dependent). For example, on OpenVMS systems, the rule pointed to by the filename in SYS$SYSTEM:SYS$TIMEZONE_SRC.DAT applies. NOTES All of the output parameters are optional. No value is returned and no error occurs if the pointer is NULL. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or an insufficient buffer. EXAMPLES See the sample program in the utc_gmtzone reference page. RELATED INFORMATION Functions: utc_anyzone utc_gmtzone utc_localtime 4 utc_mkanytime NAME utc_mkanytime - Converts a tm structure and TDF (expressing the time in an arbitrary time zone) to a binary timestamp SYNOPSIS #include int utc_mkanytime( utc_t *utc, struct tm *timetm, long tns, struct tm *inacctm, long ins, long tdf ); PARAMETERS Input timetm A tm structure that expresses the local time; tm_wday and tm_yday are ignored on input; the value of tm_isdt should be -1. tns Nanoseconds since the Time component. inacctm A tm structure that expresses days, hours, minutes, and seconds of inaccuracy. If a null pointer is passed, or if tm_yday is negative, the inaccuracy is considered to be unspecified; tm_mday, tm_mon, tm_wday, and tm_isdst are ignored on input. ins Nanoseconds of the inaccuracy component. tdf Time Differential Factor to use in conversion. Output utc Resulting binary timestamp. DESCRIPTION The utc_mkanytime() routine converts a tm structure and TDF (express- ing the time in an arbitrary time zone) to a binary timestamp. Required inputs include nanoseconds since Time and nanoseconds of inaccuracy. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES The following example converts a string ISO format time in an arbitrary time zone to a binary timestamp. This may be part of an input timestamp routine, although a real implementation will include range checking. utc_t utc; struct tm tmtime, tminacc; float tsec, isec; double tmp; long tnsec, insec; int i, offset, tzhour, tzmin, year, mon; char *string; /* Try to convert the string... */ if(sscanf(string, "%d-%d-%d-%d:%d:%e+%d:%dI%e", &year, &mon, &tmtime.tm_mday, &tmtime.tm_hour, &tmtime.tm_min, &tsec, &tzhour, &tzmin, &isec) != 9) { /* Try again with a negative TDF... */ if (sscanf(string, "%d-%d-%d-%d:%d:%e-%d:%dI%e", &year, &mon, &tmtime.tm_mday, &tmtime.tm_hour, &tmtime.tm_min, &tsec, &tzhour, &tzmin, &isec) != 9) { /* ERROR */ exit(1); } /* TDF is negative */ tzhour = -tzhour; tzmin = -tzmin; } /* Fill in the fields... */ tmtime.tm_year = year - 1900; tmtime.tm_mon = --mon; tmtime.tm_sec = tsec; tnsec = (modf(tsec, &tmp)*1.0E9); offset = tzhour*3600 + tzmin*60; tminacc.tm_sec = isec; insec = (modf(isec, &tmp)*1.0E9); /* Convert to a binary timestamp... */ utc_mkanytime(&utc, /* Out: Resultant binary timestamp */ &tmtime, /* In: tm struct that represents input */ tnsec, /* In: Nanoseconds from input */ &tminacc,/* In: tm struct that represents inacc */ insec, /* In: Nanoseconds from input */ offset); /* In: TDF from input */ RELATED INFORMATION Functions: utc_anytime utc_anyzone 4 utc_mkascreltime NAME utc_mkascreltime - Converts a NULL-terminated character string that represents a relative timestamp to a binary timestamp SYNOPSIS #include int utc_mkascreltime( utc_t *utc, char *string ); PARAMETERS Input string A NULL-terminated string that expresses a relative timestamp in its ISO format. Output utc Resulting binary timestamp. DESCRIPTION The utc_mkascreltime() routine converts a NULL-terminated string, which represents a relative timestamp, to a binary timestamp. NOTES The ASCII string must be NULL-terminated. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid results. EXAMPLES The following example converts an ASCII relative time string to its binary equivalent. utc_t utc; char str[UTC_MAX_STR_LEN]; /* Relative time of -333 days, 12 hours, 1 minute, 37.223 * seconds Inaccuracy of 50.22 seconds in the format: * -333-12:01:37.223I50.22 */ (void)strcpy((void *)str, "-333-12:01:37.223I50.22"); utc_mkascreltime(&utc, /* Out: Binary utc */ str); /* In: String */ RELATED INFORMATION Functions: utc_ascreltime 4 utc_mkasctime NAME utc_mkasctime - Converts a NULL-terminated character string that represents an absolute timestamp to a binary timestamp SYNOPSIS #include int utc_mkasctime( utc_t *utc, char *string ); PARAMETERS Input string A NULL-terminated string that expresses an absolute time. Output utc Resulting binary timestamp. DESCRIPTION The utc_mkasctime() routine converts a NULL-terminated string that represents an absolute time to a binary timestamp. NOTES The ASCII string must be NULL-terminated. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid results. EXAMPLES The following example converts an ASCII time string to its binary equivalent. utc_t utc; char str[UTC_MAX_STR_LEN]; /* July 4, 1776, 12:01:37.223 local time * TDF of -5:00 hours * Inaccuracy of 3600.32 seconds */ (void)strcpy((void *)str, "1776-07-04-12:01:37.223-5:00I3600.32"); utc_mkasctime(&utc, /* Out: Binary utc */ str); /* In: String */ RELATED INFORMATION Functions: utc_ascanytime utc_ascgmtime utc_asclocaltime 4 utc_mkbinreltime NAME utc_mkbinreltime - Converts a timespec structure expressing a relative time to a binary timestamp SYNOPSIS #include int utc_mkbinreltime( utc_t *utc, reltimespec_t *timesp, timespec_t *inaccsp ); PARAMETERS Input timesp A reltimespec structure that expresses a relative time. inaccsp A timespec structure that expresses inaccuracy. If a null pointer is passed, or if tv_sec is set to a value of -1, the inaccuracy is considered to be unspecified. Output utc Resulting relative binary timestamp. DESCRIPTION The utc_mkbinreltime() routine converts a timespec structure that expresses relative time to a binary timestamp. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES See the sample program in the utc_addtime reference page. RELATED INFORMATION Functions: utc_binreltime utc_mkbintime 4 utc_mkbintime NAME utc_mkbintime - Converts a timespec structure to a binary timestamp SYNOPSIS #include int utc_mkbintime( utc_t *utc, timespec_t *timesp, timespec_t *inaccsp, long tdf ); PARAMETERS Input timesp A timespec structure that expresses time since 1970-01-01:00:00:00.0+0:00I0. inaccsp A timespec structure that expresses inaccuracy. If a null pointer is passed, or if tv_sec is set to a value of -1, the inaccuracy is considered to be unspecified. tdf TDF component of the binary timestamp. Output utc Resulting binary timestamp. DESCRIPTION The utc_mkbintime() routine converts a timespec structure time to a binary timestamp. The TDF input is used as the TDF of the binary timestamp. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES The following example obtains the current time from time(), converts it to a binary timestamp with an inaccuracy of 5.2 seconds, and specifies GMT. timespec_t ttime, tinacc; utc_t utc; /* Obtain the current time (without the inaccuracy)... */ ttime.tv_sec = time((time_t *)0); ttime.tv_nsec = 0; /* Specify the inaccuracy... */ tinacc.tv_sec = 5; tinacc.tv_nsec = 200000000; /* Convert to a binary timestamp... */ utc_mkbintime(&utc, /* Out: Binary timestamp */ &ttime, /* In: Current time in timespec */ &tinacc, /* In: 5.2 seconds in timespec */ 0); /* In: TDF of GMT */ RELATED INFORMATION Functions: utc_bintime utc_mkbinreltime 4 utc_mkgmtime NAME utc_mkgmtime - Converts a tm structure that expresses GMT or UTC to a binary timestamp SYNOPSIS #include int utc_mkgmtime( utc_t *utc, struct tm *timetm, long tns, struct tm *inacctm, long ins ); PARAMETERS Input timetm A tm structure that expresses GMT. On input, tm_wday and tm_yday are ignored; the value of tm_isdt should be -1. tns Nanoseconds since the Time component. inacctm A tm structure that expresses days, hours, minutes, and seconds of inaccuracy. If a null pointer is passed, or if tm_yday is negative, the inaccuracy is considered to be unspecified. On input, tm_mday, tm_mon, tm_wday, and tm_isdst are ignored. ins Nanoseconds of the inaccuracy component. Output utc Resulting binary timestamp. DESCRIPTION The utc_mkgmtime() routine converts a tm structure that expresses GMT or UTC to a binary timestamp. Additional inputs include nanoseconds since the last second of Time and nanoseconds of inaccuracy. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES See the sample program in the utc_cmpintervaltime reference page. RELATED INFORMATION Functions: utc_gmtime 4 utc_mklocaltime NAME utc_mklocaltime - Converts a tm structure that expresses local time to a binary timestamp SYNOPSIS #include int utc_mklocaltime( utc_t *utc, struct tm *timetm, long tns, struct tm *inacctm, long ins ); PARAMETERS Input timetm A tm structure that expresses the local time. On input, tm_wday and tm_yday are ignored; the value of tm_isdst should be -1. tns Nanoseconds since the Time component. inacctm A tm structure that expresses days, hours, minutes, and seconds of inaccuracy. If a null pointer is passed, or if tm_yday is negative, the inaccuracy is considered to be unspecified. On input, tm_mday, tm_mon, tm_wday, and tm_isdst are ignored. ins Nanoseconds of the inaccuracy component. Output utc Resulting binary timestamp. DESCRIPTION The utc_mklocaltime() routine converts a tm structure that expresses local time to a binary timestamp. The user's environment determines the time zone rule (details are system dependent). If the user's environment does not specify a time zone rule, the system's rule is used (details of the rule are system dependent). For example, on OpenVMS systems, the rule pointed to by the filename in SYS$SYSTEM:SYS$TIMEZONE_SRC.DAT applies. Additional inputs include nanoseconds since the last second of Time and nanoseconds of inaccuracy. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES See the sample program in the utc_cmpmidtime reference page. RELATED INFORMATION Functions: utc_localtime 4 utc_mkreltime NAME utc_mkreltime - Converts a tm structure that expresses relative time to a relative binary timestamp SYNOPSIS #include int utc_mkreltime( utc_t *utc, struct tm *timetm, long tns, struct tm *inacctm, long ins ); PARAMETERS Input timetm A tm structure that expresses a relative time. On input, tm_wday and tm_yday are ignored; the value of tm_isdst should be -1. tns Nanoseconds since the Time component. inacctm A tm structure that expresses seconds of inaccuracy. If a null pointer is passed, or if tm_yday is negative, the inaccuracy is considered to be unspecified. On input, tm_mday, tm_mon, tm_year, tm_wday, tm_isdst, and tm_zone are ignored. ins Nanoseconds of the inaccuracy component. Output utc Resulting relative binary timestamp. DESCRIPTION The utc_mkreltime() routine converts a tm structure that expresses relative time to a relative binary timestamp. Additional inputs include nanoseconds since the last second of Time and nanoseconds of inaccuracy. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES The following example converts the relative time: 125-03:12:30.1I120.25 to a relative binary timestamp. utc_t utc; struct tm tmtime,tminacc; long tnsec,insec; /* Fill in the fields */ memset((void *)&tmtime,0,sizeof(tmtime)); tmtime.tm_mday = 125; tmtime.tm_hour = 3; tmtime.tm_min = 12; tmtime.tm_sec = 30; tnsec = 100000000; /* .1 * 1.0E9 */ memset((void *)&tminacc,0,sizeof(tminacc)); tminacc.tm_sec = 120; tnsec = 250000000; /* .25 * 1.0E9 */ /* Convert to a relative binary timestamp... */ utc_mkreltime(&utc, /* Out: Resultant relative binary timestamp */ &tmtime, /* In: tm struct that represents input */ tnsec, /* In: Nanoseconds from input */ &tminacc, /* In: tm struct that represents inacc */ insec); /* In: Nanoseconds from input */ 4 utc_mulftime NAME utc_mulftime - Multiplies a relative binary timestamp by a floating-point value. SYNOPSIS #include int utc_mulftime( utc_t *result, utc_t *utc1, double factor ); PARAMETERS Input utc1 Relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. factor Real scale factor (double-precision, floating-point value). Output result Resulting relative binary timestamp. DESCRIPTION The utc_mulftime() routine multiplies a relative binary timestamp by a floating-point value. Either or both may be negative; the resulting relative binary timestamp has the appropriate sign. The unsigned inaccuracy in the relative binary timestamp is also multiplied by the absolute value of the floating-point value. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES The following example scales a relative time by a floating-point factor and prints the result. utc_t relutc, scaledutc; struct tm scaledreltm; char timstr[UTC_MAX_STR_LEN]; /* Assume relutc contains the time to scale. */ utc_mulftime(&scaledutc, /* Out: Scaled rel time */ &relutc, /* In: Rel time to scale */ 17.65); /* In: Scale factor */ utc_ascreltime(timstr, /* Out: ASCII rel time */ UTC_MAX_STR_LEN, /* In: Input buffer length */ &scaledutc); /* In: Rel time to convert */ printf("%s\n",timstr); /* Convert it to a tm structure and print it. */ utc_reltime(&scaledreltm, /* Out: Scaled rel tm */ (long *)0, /* Out: Scaled rel nano-sec */ (struct tm *)0, /* Out: Scaled rel inacc tm */ (long *)0, /* Out: Scd rel inacc nanos */ &scaledutc); /* In: Rel time to convert */ printf( "Approximately %d days, %d hours and %d minutes\n", scaledreltm.tm_yday, scaledreltm.tm_hour, scaledreltm.tm_min ); RELATED INFORMATION Functions: utc_multime 4 utc_multime NAME utc_multime - Multiplies a relative binary timestamp by an integer factor SYNOPSIS #include int utc_multime( utc_t *result, utc_t *utc1, long factor ); PARAMETERS Input utc1 Relative binary timestamp. factor Integer scale factor. Output result Resulting relative binary timestamp. DESCRIPTION The utc_multime() routine multiplies a relative binary timestamp by an integer. Either or both may be negative; the resulting binary timestamp has the appropriate sign. The unsigned inaccuracy in the binary timestamp is also multiplied by the absolute value of the integer. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES The following example scales a relative time by an integral value and prints the result. utc_t relutc, scaledutc; char timstr[UTC_MAX_STR_LEN]; /* Assume relutc contains the time to scale. Scale it by a * factor of 17 ... */ utc_multime(&scaledutc, /* Out: Scaled rel time */ &relutc, /* In: Rel time to scale */ 17L); /* In: Scale factor */ utc_ascreltime(timstr, /* Out: ASCII rel time */ UTC_MAX_STR_LEN, /* In: Input buffer length */ &scakedutc); /* In: Rel time to convert */ printf("Scaled result is %s0, timstr); RELATED INFORMATION Functions: utc_mulftime 4 utc_pointtime NAME utc_pointtime - Converts a binary timestamp to three binary timestamps that represent the earliest, most likely, and latest time SYNOPSIS #include int utc_pointtime( utc_t *utclp, utc_t *utcmp, utc_t *utchp, utc_t *utc ); PARAMETERS Input utc Binary timestamp or relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output utclp Lowest (earliest) possible absolute time or shortest possible relative time that the input timestamp can represent. utcmp Midpoint of the input timestamp. utchp Highest (latest) possible absolute time or longest possible relative time that the input timestamp can represent. DESCRIPTION The utc_pointtime() routine converts a binary timestamp to three binary timestamps that represent the earliest, latest, and most likely (midpoint) times. If the input is a relative binary time, the outputs represent relative binary times. NOTES All outputs have zero inaccuracy. An error is returned if the input binary timestamp has an unspecified inaccuracy. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument. EXAMPLES See the sample program in the utc_addtime reference page. RELATED INFORMATION Functions: utc_boundtime utc_spantime 4 utc_reltime NAME utc_reltime - Converts a relative binary timestamp to a tm structure SYNOPSIS #include int utc_reltime( struct tm *timetm, long *tns, struct tm *inacctm, long *ins, utc_t *utc ); PARAMETERS Input utc Relative binary timestamp. Output timetm Relative time component of the relative binary timestamp. The field tm_mday returns a value of -1 and the fields tm_year and tm_mon return values of 0 (zero). The field tm_yday contains the number of days of relative time. tns Nanoseconds since the Time component of the relative binary timestamp. inacctm Seconds of the inaccuracy component of the relative binary timestamp. If the inaccuracy is finite, then tm_mday returns a value of -1 and tm_mon and tm_year return values of 0 (zero). The field tm_yday contains the inaccuracy in days. If the inaccuracy is unspecified, all tm structure fields return values of -1. ins Nanoseconds of the inaccuracy component of the relative binary timestamp. DESCRIPTION The utc_reltime() routine converts a relative binary timestamp to a tm structure. Additional returns include nanoseconds since Time and nanoseconds of inaccuracy. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES See the sample program in the utc_mulftime reference page. RELATED INFORMATION Functions: utc_mkreltime 4 utc_spantime NAME utc_spantime - Given two (possibly unordered) binary timestamps, returns a single UTC time interval whose inaccuracy spans the two input binary timestamps SYNOPSIS #include int utc_spantime( utc_t *result, utc_t *utc1, utc_t *utc2 ); PARAMETERS Input utc1 Binary timestamp. Use NULL if you want this routine to use the current time for this parameter. utc2 Binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output result Spanning timestamp. DESCRIPTION Given two binary timestamps, the utc_spantime() routine returns a single UTC time interval whose inaccuracy spans the two input timestamps (that is, the interval resulting from the earliest possible time of either timestamp to the latest possible time of either timestamp). NOTES The tdf parameter in the output UTC value is copied from the utc2 input. If either input binary timestamp has an unspecified inaccuracy, an error is returned. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument. EXAMPLES The following example computes the earliest and latest times for an array of 10 timestamps. utc_t time_array[10], testtime, earliest, latest; int i; /* Set the running timestamp to the first entry... */ testtime = time_array[0]; for (i=1; i<10; i++) { /* Compute the minimum and the maximum against the next * element... */ utc_spantime(&testtime, /* Out: Resultant interval */ &testtime, /* In: Largest previous interval */ &time_array[i]); /* In: Element under test */ } /* Compute the earliest and latest possible times */ utc_pointtime(&earliest, /* Out: Earliest poss time in array */ (utc_t *)0, /* Out: Midpoint */ &latest, /* Out: Latest poss time in array */ &testtime); /* In: Spanning interval */ RELATED INFORMATION Functions: utc_boundtime utc_gettime utc_pointtime 4 utc_subtime NAME utc_subtime - Computes the difference between two binary timestamps SYNOPSIS #include int utc_subtime( utc_t *result, utc_t *utc1, utc_t *utc2 ); PARAMETERS Input utc1 Binary timestamp or relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. utc2 Binary timestamp or relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output result Resulting binary timestamp or relative binary timestamp, depending upon the operation performed: + absolute time-absolute time=relative time + relative time-relative time=relative time + absolute time-relative time=absolute time + relative time-absolute time is undefined. (See the note later in this reference page.) DESCRIPTION The utc_subtime() routine subtracts one binary timestamp from another. The two binary timestamps express either an absolute time and a relative time, two relative times, or two absolute times. The resulting timestamp is utc1 minus utc2. The inaccuracies of the two input timestamps are combined and included in the output timestamp. The TDF in the first timestamp is copied to the output. NOTES Although no error is returned, the combination relative time- absolute time should not be used. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES See the sample program in the utc_binreltime reference page. RELATED INFORMATION Functions: utc_addtime 3 dtscp_commands NAME Intro - Introduction to the DCE DTS control program commands DESCRIPTION The DCE Distributed Time Service control program (dtscp) allows you to synchronize, adjust, and maintain the system clocks in a distributed network. The DTS control program commands are listed below: + The advertise command, which configures the DTS server as a global server + The change command, which modifies the epoch and sets the local time to a new time + The create command, which establishes a DTS entity (a clerk or server) + The delete command, which causes DTS to exit on the local node + The disable command, which suspends a DTS entity + The enable command, which starts a DTS entity + The exit command, which ends the dtscp management session and returns you to the system prompt + The help command which invokes the dtscp help service. + The quit command, which ends the dtscp management session and returns you to the system prompt + The set command, which modifies characteristics of a DTS entity + The show command, which displays characteristics of a DTS entity + The synchronize command, which synchronizes the system clock with the time obtained from DTS servers in the network + The unadvertise command, which removes the global server entry + The update command, which gradually adjusts the system clock to a new time RELATED INFORMATION Command: dtscp Books: DCE Administration Guide DCE Administration Reference 4 advertise NAME advertise - Configures the system as a global server by adding the server's entry to the cell profile SYNOPSIS dtscp advertise DESCRIPTION The advertise command causes DTS to forward the name and attributes of the server to CDS by binding the server's protocol tower to the CDS object and adding an entry for the server in the cell profile. Once the server's entry is in the cell profile, it is configured as a global server, and servers outside of the LAN can access it. Privilege Required You must have write permission on the ACL associated with the DTS entity in order to execute the command. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES dtscp> advertise RELATED INFORMATION Commands: unadvertise 4 change NAME change - Alters the epoch number and time on the local node SYNOPSIS dtscp change epoch integer [time absolute-time] OPTIONS epoch integer Specifies the new epoch number (0-255). This argument is required. time absolute-time Specifies a clock setting for the new epoch. If you do not supply this argument and a value, the server uses the current clock time with an unspecified inaccuracy and initiates a synchronization. This argument is optional. DESCRIPTION The change command sets the time and changes the epoch of the DTS server on which it is entered. Use this command to isolate a server from the rest of the servers in the network before changing the time. Permissions Required You must have write permission on the ACL associated with the DTS entity in order to execute the command. NOTES This command is valid only for servers. The new epoch number you specify must be different from the current epoch number. This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES 1. The following example shows how to change the epoch number: dtscp> change epoch 1 2. The following example shows how to change the epoch number and time: dtscp> change epoch 1 time 1990-11-30-10:58:00.000-05:00I0.000 4 create NAME create - Creates the DCE DTS entity on the specified node SYNOPSIS dtscp create type OPTIONS type Specifies the type of DCE DTS entity to be created on the specified node. Specify one of the following for : clerk The DCE DTS entity is created as a clerk. (The default setting is clerk.) server The DCE Distributed Time Service entity is created as a server. DESCRIPTION The create command creates a time server or time clerk entity on the system where the command is entered. After the DTS entity is created, it is still in a non-functioning state. To put it into operation, you must invoke dtscp enable, which causes an immediate synchronization to take place. For more information, see the enable reference page in this chapter. Privilege Required You must have write permission on the ACL associated with the DTS entity in order to execute the command. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE dtscp> create type server 4 delete NAME delete - Deletes the DCE DTS entity SYNOPSIS dtscp delete DESCRIPTION The delete command deletes the DCE DTS entity from the system where the command is entered. When delete is executed, the DTS daemon process completes execution. To restart the DTS daemon, use the SYS$MANAGER:DCE$SETUP.COM command procedure. Privilege Required You must have write permission on the ACL associated with the DTS entity in order to execute the command. NOTES The DCE DTS entity cannot be deleted until you enter the disable command, which causes the status attribute state to be set to off. This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE dtscp> delete RELATED INFORMATION Commands: disable 4 disable NAME disable - Stops the DCE DTS entity on the local node SYNOPSIS dtscp disable DESCRIPTION The disable command turns off the DCE DTS entity on the system where the command is entered. When the command is executed, the status attribute state is set to off. Privilege Required You must have write permission on the ACL associated with the DTS entity in order to execute the command. NOTES The DCE DTS entity cannot be disabled until it is enabled with the enable command. You must enter the disable command before you can delete the entity. This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES dtscp> disable RELATED INFORMATION Commands: enable delete create 4 enable NAME enable - Starts the DTS entity on the local node. SYNOPSIS dtscp enable [set clock ] ARGUMENTS set clock Specifies whether the clock is abruptly set or gradually adjusted to the computed time. This argument is optional. Valid values for are: false The clock is gradually adjusted. This is the default condition. true The clock is abruptly set. DESCRIPTION After the DTS entity is created with the dtscp create command, it is still in a non-functioning state. To put it into operation, you must invoke dtscp enable, which causes an immediate synchronization to take place. When the command is executed, the status attribute state is set to on. In addition, you may use the enable command to activate a DTS entity that has previously been deactivated with the disable command. See the disable reference page in this chapter for more information. Privilege Required You must have write permission on the ACL associated with the DTS entity in order to execute the command. NOTES The DTS entity cannot be enabled until it is created with the create command; the DTS entity must be in the off state. This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES 1. The following example shows how to enable the entity and adjust the clock gradually to the computed time following the first synchronization: dtscp> enable 2. The following example shows how to enable the entity and abruptly set the clock to the computed time following the first synchronization: dtscp> enable set clock true RELATED INFORMATION Commands: create disable 4 exit NAME exit - Causes dtscp to complete execution. SYNOPSIS dtscp exit DESCRIPTION The exit command causes the DTS control program (dtscp) to complete execution and returns operation to the parent process. NOTE This command may be replaced in future releases by the dcecp command, and may no longer be supported at that time. EXAMPLES The following command shows how to leave dtscp and return to the parent process: dtscp> exit RELATED INFORMATION Commands: quit 4 help NAME help - Displays help information about dtscp commands. SYNOPSIS dtscp help [help-topic] ARGUMENTS help-topic Specifies the help topic for which help information is to be displayed. The following are valid help topics: + advertise + change + create + delete + disable + enable + set + show + synchronize + unadvertise + update DESCRIPTION The help command displays information about dtscp commands. NOTE This command may be replaced in future releases by the dcecp command, and may no longer be supported at that time. EXAMPLES The following command shows how to get help about the help subtopic unadvertise. dtscp> help unadvertise 4 quit NAME quit - Causes dtscp to complete execution SYNOPSIS dtscp quit DESCRIPTION The quit command causes dtscp to complete execution and returns operation to the parent process. NOTE This command may be replaced in future releases by the dcecp command, and may no longer be supported at that time. EXAMPLES The following command shows how to leave dtscp and return to the parent process: dtscp> quit RELATED INFORMATION Command: exit 4 set NAME set - Modifies characteristics for the DTS entity. SYNOPSIS dtscp set characteristic ARGUMENTS characteristic The name and value of one or more characteristics to be modified. Valid values for characteristic are described in the following list. These values are described in more detail in the description section. + check interval [relative-time] + courier role [role] + error tolerance [relative-time] + global set timeout [relative-time] + local set timeout [relative-time] + maximum inaccuracy [relative-time] + query attempts [integer] + server entry name [name] + server group name [name] + server principal name [name] + servers required [integer] + synchronization hold down [relative-time] DESCRIPTION The set command modifies the charactistics you specify for the DTS entity. The modifiable characteristics and their values are described in the following list. check interval [relative-time] Specifies the amount of time between checks for faulty servers. Applicable only for servers that have external time providers. Default: 0-01:30:00.000 Value: 0-00:00:30.000 - 10675199-02:48:05.000 courier role [role] Specifies a server's interaction with the set of global servers. Default: backup courier The following values are valid: backup courier The local server becomes a courier if none are available on the LAN. courier The local server synchronizes with the global set of servers. noncourier The local server does not synchronize with the global set of servers. error tolerance [relative-time] Specifies the maximum separation allowed between the local clock and the computed time before synchronizations become abrupt rather than gradual (monotonic). Default: 0-00:10:00.000 Value: 0-00:00:00.500 - 10675199-02:48:05.000 global set timeout [relative-time] Specifies the amount of time the node waits for a response to a global synchronization request before sending another request or declaring a global server to be unavailable. The number of attempts made to reach the server is controlled by the query attemps characteristic. Default: 0-00:00:15.000 Value: 0-00:00:00.000 - 0-00:10:00.000 local set timeout [relative-time] Specifies the amount of time the node waits for a response to a local synchronization request before sending another request or declaring a server to be unavailable. The number of attempts made to reach the server is controlled by the query attemps characteristic. Note that the local set timeout value controls only the initial contact with a time provider. During this initial contact, the time provider itself determines the timeout value for actually reporting back times. This allows a time provider attached to a slow source like a modem to request that dtsd wait for a longer interval. Default: 0-00:00:05.000 Value: 0-00:00:00.000 - 0-00:01:00.000 maximum inaccuracy [relative-time] Specifies the inaccuracy limit for the node. When the node exceeds the maximum inaccuracy setting, it attempts to synchronize. Default: 0-00:00:00.100 Value: 0-00:00:00.000 - 10675199-02:48:05.000 query attempts [integer] Specifies the number of attempts that a node makes to contact a server before the node considers the server unavailable. Default: 3 Value: 1-10 server entry name [name] Specifies a server's CDS entry name; hostname represents the name of the system or node that is the server's client. The default setting is the recommended value. Default: /.:/hosts/hostname/dts-entity server group name [name] Specifies the name of the security group that DTS uses for authentication checks. DTS clerks and servers do not accept time values from DTS servers that are not included in this group. server principal name [name] Specifies a server's principal name for authentication purposes; hostname represents the name of the system or node that is the server's client. The default setting is the recommended value. Default: /.:/hosts/hostname/self servers required [integer] Specifies the minimum number of servers required for a synchronization. Settings of 1 or 2 may cause unreliable computed times. Default: 1 (clerks) 3 (servers) Value: 1-10 synchronization hold down [relative-time] Specifies the interval a node must wait to synchronize. Also specifies synchronization frequency when a node reaches the value specified by the maximum inaccuracy characteristic. Clerks: Default: 0-00:10:00.000 Value: 0-00:00:30.000 - 01-00:00:00.000 Servers: Default: 0-00:02:00.000 Value: 0-00:00:30.000 - 01-00:00:00.000 Privilege Required You must have write permission on the ACL associated with the DTS entity in order to execute the command. NOTES This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. The following two commands are obsolete. Use the replacements shown. set lan timeout This command is the same as set local set timeout. set wan timeout This command is the same as set global set timeout. EXAMPLES 1. The following example command sets the check interval characteristic to 30 seconds: dtscp> set check interval 00-00:00:30.000 2. The following example shows how to set the number of servers required before the entity can synchronize: dtscp> set servers required 4 3. The following example shows how to set the courier role for a server: dtscp> set courier role backup courier 4. The following example command sets the error tolerance characteristic to seven minutes: dtscp> set error tolerance 0-00:07:00.000 5. The following example command the global set timeout characteristic to 45 seconds: dtscp> set global set timeout 0-00:00:45.000 6. The following example command the local set timeout charac- teristic to five seconds: dtscp> set local set timeout 0-00:00:05.000 7. The following example command sets the maximum inaccuracy characteristic to three milliseconds: dtscp> set maximum inaccuracy 0-00:00:00.300 8. The following example command sets the server entry name characteristic to /.:/hosts/orion/dts-entity: dtscp> set server entry name /.:/hosts/orion/dts-entity 9. The following example command sets the server principal name characteristic to /.:/hosts/vega/dts-entity: dtscp> set server principal name /.:/hosts/vega/dts-entity 10. The following example command sets the synchronization hold down characteristic to 15 minutes: dtscp> set synchronization hold down 0-00:15:00.000 RELATED INFORMATION Commands: show 4 show NAME show - Displays current information about the DTS entity SYNOPSIS dtscp show attribute-group | attribute-name ARGUMENTS attribute-group The name of an attribute group or individual attribute to be displayed. The following values are valid: + all + all characteristics + all counters + all status + global servers + local servers attribute-name The name of a specific attribute from the characteristics, counters, or status group. The attribute specifiers global servers and local servers do not contain any other attributes. DESCRIPTION The show command displays the names and values of the specified attributes or attribute groups. For attribute groups, if you do not supply a group name with the all argument, all characteristics and their values are displayed. The following sections list names of individual attributes, categorized by group. Note that the attributes displayed by the show command might be different, depending upon whether you have requested information about a server or a clerk. Characteristics Characteristic arguments can contain a maximum of 80 characters and are recalculated to a normalized date format. For example: Input value: 0-0025:10:99.99999999 Result: 1-01:11:39.990 acting courier role Specifies whether a backup courier is currently functioning as a courier. If the role is noncourier, the node is not attempting to synchronize with global servers. This characteristic is shown only for servers. Default: noncourier Value: courier or noncourier automatic tdf change Specifies whether automatic changes to the time differential factor are enabled or disabled; the value is determined by the operating system. Default: true Value: true/false check interval Specifies the amount of time between checks for faulty servers. Applicable only to servers that have external time providers. This characteristic is shown only for servers. Default: 0-01:30:00.00 Value: 0-00:00:30.000 - 10675199-02:48:05.478 clock adjustment rate Specifies the rate at which the DTS server or clerk entity adjusts the node's clock during a synchronization. clock resolution Specifies the amount of time between system clock ticks. The value is determined by the operating system. courier role Specifies a server's interaction with the set of global servers. This characteristic is shown only for servers. backup courier The local server becomes a courier if none are available on the LAN. courier The local server synchronizes with the global set of servers. noncourier The local server does not synchronize with the global set of servers. Default: noncourier DTS version Specifies the DTS software version installed on the node. epoch number Specifies the server's epoch number. The change command modifies this characteristic. This characteristic is shown only for servers. Default: 0 Value: 0-255 error tolerance Specifies the maximum separation allowed between the local clock and the computed time before synchronizations become abrupt rather than gradual (monotonic). Default: 0-00:10:00.000 Value: 0-00:00:00.500 - 10675199-02:48:05.478 global set timeout Specifies the amount of time the node waits for a response to a WAN synchronization request before sending another request or declaring a global server to be unavailable. The number of attempts made to reach the server is controlled by the query attemps characteristic. Default: 0-00:00:15.000 Value: 0-00:00:00.000 - 0-00:10:00.000 local set timeout Specifies the amount of time the node waits for a response to a synchronization request before sending another request or declaring a server to be unavailable. The number of attempts made to reach the server is controlled by the query attemps characteristic. Default: 0-00:00:05.000 Value: 0-00:00:00.000 - 0-00:10:00.000 local time differential factor Specifies the Time Differential Factor (TDF), which is the amount of time the server varies from Greenwich mean time (GMT) or Coordinated Universal Time (UTC). Default: 0-00:00:00.000 Value: -13-00:00:00 - 13-00:00:00 maximum clock drift rate Specifies the worst-case drift rate of the node's clock, in nanoseconds per second, as determined by the manufacturer's specifications. maximum inaccuracy Specifies the inaccuracy limit for the node. When the node exceeds the maximum inaccuracy setting, it attempts to synchronize. Default: 0-00:00:00.100 Value: 0-00:00:00.0 - 10675199-02:48:05.478 next tdf change Specifies the future time at which the time differential factor is automatically changed. The value is determined by the operating system. query attempts Specifies the number of attempts that a node makes to contact a server before the node considers the server unavailable. Default: 3 Value: 1-10 server entry name Specifies a server's ACL entry name; represents the name of the system or node that is the server's client. The default setting is the recommended value. This characteristic is shown only for servers. Default: /.:/hosts//dts-entity server group name Specifies the security group name for the time servers within the cell. Default: /.:/subsys/dce/dts-servers server principal name Specifies a server's principal name for authentication purposes; represents the name of the system or node that is the server's client. The default setting is the recommended value. This characteristic is shown only for servers. Default: /.:/hosts//self servers required Specifies the minimum number of servers required for a synchronization. Settings of 1 or 2 may cause unreliable computed times. Default: 3 Value: 1-10 synchronization hold down Specifies the interval a node must wait to synchronize. Also specifies synchronization frequency when a node reaches the value specified by the maximum inaccuracy characteristic. Clerks: Default: 0-00:10:00.0 Value: 0-00:00:30.0 - 01 00:00:00.00 Servers: Default: 0-00:02.00.0 Value: 0-00:00:30.0 - 01 00:00:00.00 time provider present Specifies whether or not the entity used an external time provider at the last successful synchronization. This attribute applies to servers only. time representation version Specifies the timestamp format used by the node. type Specifies whether the node is a DTS server or clerk. The create command modifies this characteristic. Counters clock settings Specifies the number of times the node clock has been set nonmonotonically (abruptly). creation time Specifies the time at which the DTS entity was created and the counters were initialized. different epochs detected Specifies the number of times the node received time response messages from servers or clerks that had epoch numbers different from its own. This counter is shown only for servers. disable directives completed Specifies the number of times the DTS has been disabled. enable directives completed Specifies the number of times the DTS has been enabled. epoch changes completed Specifies the number of times the server's epoch has changed. insufficient resources detected Specifies the number of times the node has been unable to allocate virtual memory. local servers not in group Specifies the number of times that a local server was contacted, but it was not in the dts security group. local times not intersecting Specifies the number of times the node's time interval failed to intersect with the computed interval of the servers. no global servers detected Specifies the number of times the courier server could not contact any global servers. This counter is shown only for servers. protocol mismatches detected Specifies the number of times the local node failed to process a received message containing an incompatible protocol version. servers not in group Specifies the number of times that a non-local server was contacted, but it was not in the dts security group. This counter is shown only for servers. servers not responding Specifies the number of times the courier server could not contact a specific global server. This counter is shown only for servers. servers times not intersecting Specifies the number of times a server has detected faulty servers (other than itself). This counter is shown only for servers. synchronizations completed Specifies the number of times the node successfully synchronized. system errors detected Specifies the number of times a DTS operation detected a system error. time provider failures detected Specifies the number of times the external time provider signaled a failure or the node was unable to access the time provider. time provider timeouts detected Specifies the number of times a dtsd server process initiated contact with a time provider and did not receive the initial response within the interval specified by local set timeout (the default interval is 5 seconds). This counter is shown only for servers. time representation version mismatches detected Specifies the number of times the local node failed to process a received message containing an incompatible timestamp format. too few servers detected Specifies the number of times a node failed to synchronize because it could not contact the required minimum number of servers. updates initiated Specifies the number of times a server has attempted to update its clock. This counter is shown only for servers. Status current time Specifies the current time on the node. global servers Specifies the set of global servers known by the node. last synchronization Specifies the computed time at the last attempted synchronization. local servers Specifies the set of local servers known by the node. state Specifies the state of the DTS entity. off The DTS entity is disabled. on The DTS entity is enabled. synchronizing The DTS entity is synchronizing. updating The DTS entity is updating the time. uid Specifies the entity's unique identifier, which is generated when the entity is created. This attribute is shown only for servers. Privilege Required You must have read permission on the ACL associated with the DTS entity in order to execute the command. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES 1. The following command shows how to display the current time: dtscp> show current time Current Time = 1990-11-30-12:11:41.718-05:00I0.359 EST 2. The following command shows how to display all of the entity's characteristic attribute settings: dtscp> show all Check Interval = +0-01:30:00.000I----- Epoch Number = 0 Error Tolerance = +0-00:10:00.000I----- Local Time Differential Factor = -0-04:00:00.000I----- Maximum Inaccuracy = +0-00:00:00.100I----- Servers Required = 3 Query Attempts = 3 Local Set Timeout = +0-00:00:05.000I----- Global Set Timeout = +0-00:00:15.000I----- Synchronization Hold Down = +0-00:02:00.000I----- Type = Server Courier Role = NonCourier Acting Courier Role = NonCourier Clock Adjustment Rate = 40000000 nsec/sec Maximum Clock Drift Rate = 1000000 nsec/sec Clock Resolution = 10000000 nsec DTS Version = V1.0.1 Time Representation Version = V1.0.0 Time Provider Present = FALSE Automatic TDF Change = FALSE Next TDF Change = 1993-10-31-06:00:00.000+00:00I0.000 Server Principal Name = hosts/system1/self Server Entry Name = hosts/system1/dts-entity Server Group Name = subsys/dce/dts-servers 3. The following command displays the current values of all characteristic attributes: dtscp> show all characteristics This command produces the same output as does the show all command. 4. The following command shows how to display all of the local servers known to the entity: dtscp> show local servers Known Servers ============================================================ Local /.../sisyphus.osf.org/hosts/system2/self Last Time Polled = 1993-10-15-21:01:46.124+00:00I0.809 Last Observed Time = 1993-10-15-21:03:09.041+00:00I----- Last Observed Skew = +0-00:01:22.917I----- Used in Last Synchronization = TRUE Transport Type = RPC Local /.../sisyphus.osf.org/hosts/system3/self Last Time Polled = 1993-10-15-21:01:46.124+00:00I0.809 Last Observed Time = 1993-10-15-21:01:46.143+00:00I0.817 Last Observed Skew = +0-00:00:00.019I1.625 Used in Last Synchronization = TRUE Transport Type = RPC 5. The following command displays the current values of all counter attributes: dtscp> show all counters Creation Time = 1993-10-14-16:23:57.801+00:00I0.767 Local Times Not Intersecting = 0 Server Times Not Intersecting = 0 Different Epochs Detected = 0 Too Few Servers Detected = 0 Time Provider Timeouts Detected = 1 Protocol Mismatches Detected = 0 Time Representation Mismatches Detected = 0 No Global Servers Detected = 0 Servers Not Responding = 0 Clock Settings = 0 Epoch Changes Completed = 0 System Errors Detected = 0 Synchronizations Completed = 865 Updates Initiated = 0 Enable Directives Completed = 1 Disable Directives Completed = 0 Insufficient Resources Detected = 0 Time Provider Failures Detected = 0 Local server not in group = 0 Servers not in group = 0 6. The following command displays the current values of all status attributes: dtscp> show all status UID = 00004e34-5e1c-2c87-8500-08005a0d4582 Last Synchronization = 1993-10-15-21:05:43.023+00:00I----- State = On 7. The following command displays the current value of the courier role attribute: dtscp> show courier role Courier Role = NonCourier 8. The following command displays the server entry name for this server: dtscp> show server entry name Server Entry Name = hosts/system1/dts-entity 9. The following command displays the current state of the Time Service entity: dtscp> show state State = On 10. The following command displays the current value of the check interval attribute: dtscp> show check interval Check Interval = +0-01:30:00.000I----- 11. The following command displays the current value of the servers times not intersecting counter: dtscp> show servers times not intersecting Server Times Not Intersecting = 0 RELATED INFORMATION Commands: set 4 synchronize NAME synchronize - Causes the DTS entity to synchronize the clock on the system where the command is entered. SYNOPSIS dtscp synchronize [set clock boolean] ARGUMENTS set clock boolean Specifies whether the clock is abruptly set or gradually adjusted to the computed time. This argument is optional. The following values are valid: false The clock is gradually adjusted. This is the default condition. true The clock is abruptly set. DESCRIPTION The synchronize command causes the DTS clerk or server to solicit time intervals from servers, compute the intersection of the time intervals, and adjust the system clock to the midpoint of the computed time interval. This command overrides the functions of the synchronization hold down characteristic. Privilege Required You must have write permission on the ACL associated with the DTS entity in order to execute the command. NOTES The synchronize command does not execute if the entity is already synchronizing or is disabled; the entity must be in the on state. This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES 1. The following example shows how to initiate a synchronization for the entity, followed by a gradual clock adjustment: dtscp> synchronize 2. The following example shows how to initiate a synchronization for the entity, followed by an abrupt reset of the clock: dtscp> synchronize set clock true 4 unadvertise NAME unadvertise - Removes the global server entry from the cell profile SYNOPSIS dtscp unadvertise DESCRIPTION The unadvertise command causes DTS to remove the server's name from the cell profile and binding from the related CDS entry, deleting the server's global status. Privilege Required You must have write permission on the ACL associated with the DTS entity in order to execute the command. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES dtscp> unadvertise RELATED INFORMATION Commands: advertise 4 update NAME update - Gradually adjusts the clock on the local node to the specified time SYNOPSIS dtscp update time absolute-time ARGUMENTS time absolute-time Specifies the absolute time to which the clock is adjusted. This argument is required. DESCRIPTION The update command gradually adjusts the system clock to a new time, beginning at the time specified in the argument. The difference between the current clock value and the absolute time specified in the argument is used to adjust the clock. Privilege Required You must have write permission on the ACL associated with the DTS entity in order to execute the command. NOTES The update command is valid only for servers. The combined time and inaccuracy value you specify must be contained within the interval formed by the current time and inaccuracy. That is, the new setting must be more accurate than the current time. This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES The following example shows how to update the time for a server; the clock is gradually adjusted to the specified time: dtscp> update time 1993-12-30-11:24:00.000-05:00I0.000 3 dtscp_intro NAME dtscp - DTS control program SYNOPSIS dtscp NOTES With the exception of the following subcommands, this command is replaced at Revision 1.1 by the dcecp command. This command may be fully replaced by the dcecp command in a future release of DCE, and may no longer be supported at that time. + exit + help + quit DESCRIPTION This section describes the commands for the DCE Distributed Time Service (DTS) control program (dtscp). The DTS control program is a command-line interface that enables you to synchronize, adjust, and maintain the system clocks in a distributed network. For a detailed explanation of system clock synchronization and management, see the OSF DCE Administration Guide. The DTS control program commands are + The advertise command, which configures the DTS server as a global server + The change command, which modifies the epoch and sets the local time to a new time + The create command, which establishes a DTS entity (a clerk or server) + The delete command, which causes DTS to exit on the local node + The disable command, which suspends a DTS entity + The enable command, which starts a DTS entity + The exit command, which ends the dtscp management session and returns you to the system prompt + The help command which invokes the dtscp help service. + The quit command, which ends the dtscp management session and returns you to the system prompt + The set command, which modifies characteristics of a DTS entity + The show command, which displays characteristics of a DTS entity + The synchronize command, which synchronizes the system clock with the time obtained from DTS servers in the network + The unadvertise command, which removes the global server entry + The update command, which gradually adjusts the system clock to a new time For more information on any of the above dtscp commands, see the appropriate reference page in this chapter. You can use control program commands from within the control program or from the system prompt. To enter DTS commands from within the control program, first start the control program by entering the dtscp command. For example: $ dtscp dtscp> At this prompt you can enter any control program command; for example: dtscp> show current time To leave the control program and return to the system prompt, enter the exit command. To enter DTS commands from the system prompt (interactively or in a command procedure) enter the dtscp command with an internal command of the control program as the first argument. The control program executes the command without displaying the control program prompt. For example, you can enter the synchronize command as follows: $ dtscp synchronize Some dtscp commands have optional arguments or attributes; there may also be optional variables for the arguments and attributes. See the following sample command: dtscp> update time 1990-08-03-05:45:28.000+01:00I00.500 / / / Command [Argument] Variable -------- [Attribute] Abbreviations You can enter as few as three characters for each DTS command or argument; DTS commands and arguments are unique for three characters or more. For example, rather than entering the command enable set clock true, you can enter the following abbreviated command: dtscp> ena set clo tru Attributes The dtscp set and show commands have several attributes-pieces or sets of data associated with them. The attribute groups are categorized as follows: Characteristics Set or show the entity's operation. Counters Show the number of occurrences of an event since the entity was enabled. Status Show the current state of the entity. (The DTS entity has four status attributes.) Global Servers Show the global servers known by this DTS entity. Local Servers Show the local servers known by this DTS entity. Individual attributes within each of the previously listed groups are described in the reference pages for the set and show commands. The show command also allows you to specify attribute groups. Time Stamps All responses to commands contain a timestamp. The following example shows a typical DTS time display: 1993-03-16-14:29:47.52000-05:00I000.003 The timestamp uses the DTS format that is explained in Chapter 15 of the OSF DCE Administration Guide-Core Components. In this example, the year is 1993, the day is March 16, and the time is 14 hours, 29 minutes, and 47.52 seconds. A negative Time Differential Factor (TDF) of 5 hours and an inaccuracy of 3 milliseconds are included in the timestamp. An inaccuracy value of I----- indicates an infinite inaccuracy. This value appears in time displays before a node's initial synchronization or after you enter the change command without specifying an inaccuracy value. RELATED INFORMATION Commands: advertise change create delete disable enable exit help set show synchronize quit unadvertise update Books: OSF DCE Administration Guide 3 dtsd NAME dtsd - Restarts the DTS daemon SYNOPSIS dtsd [options] [-d] [-w serviceability] dtsd [-s [-k courier|noncourier] [-g] [-o]] dtsd -c ARGUMENTS -d Debug mode. -w serviceability See svcroute for the full description of the appropriate format for this entry. Only the three-field format, severity:how:where, is used. An example is: FATAL:STDERR:FILE:dce_local/var/svc/fatal.log -s Run as a server. Default is backup, courier, local server -g Run dtsd as a global server. -k courier Run dtsd as a courier. -k noncourier Run dtsd as a noncourier. -o When enabling as a server, set the clock immediately. Equivalent to the command enable set clock true in dtscp or to the command dcecp dts activate -abruptly. -c Run dtsd as a clerk. DESCRIPTION The dtsd command restarts the DTS daemon (clerk or server process). When the host system is rebooted, this command is automatically executed as part of the overall DCE configuration procedure. You can enter the command manually if a DTS daemon fails to start automatically upon reboot, or if you want to restart a daemon that you disable and delete to perform a backup or do diagnostic work. After the process starts, you must execute the dtscp commands to create and enable to run DTS. Privilege Required Only the local host machine principal can start the DTS daemon. See the Security reference pages for information about principals. NOTES Use dtsd interactively only when troubleshooting; use the SYS$MANAGER:DCE$SETUP.COM command procedure to start the DTS daemon for all other instances. EXAMPLES To restart the daemon for troubleshooting, follow these steps: 1. Log in to the system. 2. Log in to DCE as the machine principal of the local host. Enter the principal name in the format hosts/hostname/self as shown in the following example command for a host named mystic whose password is smith: $ dce_login hosts/mystic/self smith 3. Enter the following command to see if the required processes are already running: $ @SYS$MANAGER:DCE$SETUP SHOW If the list of active processes does not indicate missing daemons, proceed to step 4. If any process is missing from the list of active processes, enter the following command to start them: $ @SYS$MANAGER:DCE$SETUP START 4. Enter the following command to restart the server: $ STOP/ID= $ dtsd :== $sys$system:dce$dtsd $ dtsd - [-] RELATED INFORMATION Commands: dtscp create enable Books: OSF DCE Administration Guide 2 DCE_RPC The Remote Procedure Call (RPC) service provides connections between individual procedures in an application across heterogeneous systems in a transparent way. 3 Application_Commands NAME rpc_intro - Introduction to the DCE RPC programmer commands DESCRIPTION DCE RPC provides the following programmer commands: + The idl command invokes the Interface Definition Language (IDL) compiler to convert an interface definition, written in IDL, to output files. + The uuidgen command creates a UUID string that you assign to an object to uniquely distinguish it from other objects. See each command's reference page for further information. IDL Base Data Types and IDL-to-C The following table lists the IDL base data type specifiers. Where applicable, the table shows the size of the corresponding transmittable type and the type macro emitted by the IDL compiler for resulting declarations. Base Data Type Specifiers - rpc_intro ___________________________________________________________ Specifier Type Macro (sign) (size) (type) Size Emitted by idl ___________________________________________________________ small int 8 bits idl_small_int short int 16 bits idl_short_int long int 32 bits idl_long_int hyper int 64 bits idl_hyper_int unsigned small int 8 bits idl_usmall_int unsigned short int 16 bits idl_ushort_int unsigned long int 32 bits idl_ulong_int unsigned hyper int 64 bits idl_uhyper_int float 32 bits idl_short_float double 64 bits idl_long_float char 8 bits idl_char boolean 8 bits idl_boolean byte 8 bits idl_byte void - idl_void_p_t handle_t - - Note that you can use the idl_ macros in the code you write for an application to ensure that your type declarations are consistent with those in the stubs, even when the application is ported to another platform. The idl_ macros are especially useful when passing constant values to RPC calls. For maximum portability, all constants passed to RPC calls declared in your network interfaces should be cast to the appropriate type because the size of integer constants (like the size of the int data type) is unspecified in the C language. The idl_ macros are defined in dce/idlbase.h, which is included by header files that the IDL compiler generates. RELATED INFORMATION Commands: idl uuidgen Messages: OSF DCE Problem Determination Guide. Books: OSF DCE Application Development Guide. 3 API_Runtime_Intro NAME rpc_intro - Introduction to the DCE RPC API runtime DESCRIPTION This introduction gives general information about the DCE RPC Application Programming Interface (API) and an overview of the following parts of the DCE RPC API runtime: + Runtime services + Environment variables + Data types and structures + Permissions required + Frequently used routine arguments 4 General_Information The following subsections contain topics, beyond those directly related to the RPC API, that application programmers need to know. IDL-to-C Mappings The Interface Definition Language (IDL) compiler converts an interface definition into output files. The rpc_intro reference page in the OSF DCE Command Reference contains a summary of the idl command, which invokes the IDL compiler. Additional information about the IDL compiler appears in the following table, which shows the IDL base types and the IDL-to-C mappings. The following table lists the IDL base data type specifiers. Where applicable, the table shows the size of the corresponding transmittable type and the type macro emitted by the IDL compiler for resulting declarations. Base Data Type Specifiers - rpc_intro ___________________________________________________________ Specifier Type Macro (sign) (size) (type) Size Emitted by idl ___________________________________________________________ small int 8 bits idl_small_int short int 16 bits idl_short_int long int 32 bits idl_long_int hyper int 64 bits idl_hyper_int unsigned small int 8 bits idl_usmall_int unsigned short int 16 bits idl_ushort_int unsigned long int 32 bits idl_ulong_int unsigned hyper int 64 bits idl_uhyper_int float 32 bits idl_short_float double 64 bits idl_long_float char 8 bits idl_char boolean 8 bits idl_boolean byte 8 bits idl_byte void - idl_void_p_t handle_t - - Note that you can use the idl_ macros in the code you write for an application to ensure that your type declarations are consistent with those in the stubs, even when the application is ported to another platform. The idl_ macros are especially useful when passing constant values to RPC calls. For maximum portability, all constants passed to RPC calls declared in your network interfaces should be cast to the appropriate type because the size of integer constants (like the size of the int data type) is unspecified in the C language. The idl_ macros are defined in SYS$COMMON:[DCE$LIBRARY]IDLBASE.H, which is included by header files that the IDL compiler generates. Management Commands for Programmers In addition to the idl command for programmers, DCE RPC provides two management commands for the RPC control program and the DCE Host daemon, as follows: + The rpccp control program accesses RPCCP, the RPC control program. This program provides a set of commands for accessing the operations of the RPC Name Service Interface (NSI operations). RPCCP also supports showing the elements of the local endpoint map and removing elements from it. You can manage the name service with RPCCP commands or with DCE RPC runtime routines. For example, suppose you want to obtain the members of a group. You can give the show group command to RPCCP or you can write an application program that calls the following DCE RPC runtime routines: - rpc_ns_group_mbr_inq_begin() - rpc_ns_group_mbr_inq_next() - rpc_ns_group_mbr_inq_done() + The dced command starts the DCE Host daemon. The daemon maintains the local endpoint map for RPC servers and looks up endpoints for RPC clients. See the OSF DCE Administration Reference for more information about these two management commands. 4 Overview_of_DCE_RPC_Runtime_Services The RPC runtime services consist of RPC routines that perform a variety of operations. Note that the RPC API is thread safe and synchronous cancel safe (in the context of POSIX threads). However, the RPC API is not asynchronous cancel safe. For more information about threads and their cancellation, see the OSF DCE Application Development Guide - Core Components. The rest of this overview consists of the following items: + An explanation of abbreviations in the names of the RPC runtime routines + An alphabetical list of DCE RPC runtime routines. With each routine name is its description and the type of application program that most likely calls the routine. An alphabetical list of abbreviations in the names of the DCE RPC routines follows. The list can help you remember the names more easily. For example, consider the routine name rpc_mgmt_ep_elt_inq_begin(). Use the next list to expand the name to "RPC management endpoint element inquiry begin", which summarizes the description "Creates an inquiry context for viewing the elements in a local or remote endpoint map. (Management)." auth - authentication, authorization com - communications cs - character/code set interoperability dce - distributed computing environment dflt - default elt - element ep - endpoint exp - expiration fn - function id - identifier idl_es - IDL encoding services if - interface inq - inquiry mbr - member mgmt - management ns - name service protseq - protocol sequence rgy - DCE character and code set registry rpc - remote procedure call stats - statistics An alphabetical list of the RPC runtime routines follows. With each routine name is its description and the type of application program that most likely calls the routine. cs_byte_from_netcs() Converts international character data from a network code set to a local code set. (Client, server). cs_byte_local_size() Calculates the necessary buffer size for a code set conversion from a network code set to a local code set. (Client, server). cs_byte_net_size() Calculates the necessary buffer size for a code set conversion from a local code set to a network code set. (Client, server). cs_byte_to_netcs() Converts international character data from a local code set to a network code set. (Client, server). dce_cs_loc_to_rgy() Maps a local name for a code set to a code set value in the code set registry. (Client, server). dce_cs_rgy_to_loc() Maps a code set value in the code set registry to a the local name for a code set. (Client, server). idl_es_decode_buffer() Returns a buffer decoding handle. (Client, server). idl_es_decode_incremental() Returns an incremental decoding handle. (Client, server). idl_es_encode_dyn_buffer() Returns a dynamic buffer encoding handle. (Client, server). idl_es_encode_fixed_buffer() Returns a fixed buffer encoding handle. (Client, server). idl_es_encode_incremental() Returns an incremental encoding handle. (Client, server). idl_es_handle_free() Frees an IDL encoding services handle. (Client, server). idl_es_inq_encoding_id() Identifies an application encoding operation. (Client, server). rpc_binding_copy() Returns a copy of a binding handle. (Client or server). rpc_binding_free() Releases binding handle resources. (Client or server). rpc_binding_from_string_binding() Returns a binding handle from a string representation of a binding handle. (Client or management). rpc_binding_inq_auth_client() Returns authentication and authorization information from the binding handle for an authenticated client. (Server). rpc_binding_inq_auth_info() Returns authentication and authorization information from a server binding handle. (Client). rpc_binding_inq_object() Returns the object UUID from a binding handle. (Client or server). rpc_binding_reset() Resets a server binding handle so the host remains specified, but the server instance on that host is unspecified. (Client or management). rpc_binding_server_from_client() Converts a client binding handle to a server binding handle. (Server). rpc_binding_set_auth_info() Sets authentication and authorization information into a server binding handle. (Client). rpc_binding_set_object() Sets the object UUID value into a server binding handle. (Client). rpc_binding_to_string_binding() Returns a string representation of a binding handle. (Client, server, or management). rpc_binding_vector_free() Frees the memory used to store a vector and binding handles. (Client or server). rpc_cs_binding_set_tags() Places code set tags into a server binding handle. (Client). rpc_cs_char_set_compat_check() Evaluates character set compatibility between a client and a server. (Client). rpc_cs_eval_with_universal() Evaluates a server's supported character sets and code sets during the server binding selection process. (Client). rpc_cs_eval_without_universal() Evaluates a server's supported character sets and code sets during the server binding selection process. (Client). rpc_cs_get_tags() Retrieves code set tags from a binding handle. (Client, server). rpc_ep_register() Adds to, or replaces, server address information in the local endpoint map. (Server). rpc_ep_register_no_replace() Adds to server address information in the local endpoint map. (Server). rpc_ep_resolve_binding() Resolves a partially bound server binding handle into a fully bound server binding handle. (Client or management). rpc_ep_unregister() Removes server address information from the local endpoint map. (Server). rpc_if_id_vector_free() Frees a vector and the interface identifier structures it contains. (Client, server, or management). rpc_if_inq_id() Returns the interface identifier for an interface specification. (Client or server). rpc_mgmt_ep_elt_inq_begin() Creates an inquiry context for viewing the elements in a local or remote endpoint map. (Management). rpc_mgmt_ep_elt_inq_done() Deletes the inquiry context for viewing the elements in a local or remote endpoint map. (Management). rpc_mgmt_ep_elt_inq_next() Returns one element at a time from a local or remote endpoint map. (Management). rpc_mgmt_ep_unregister() Removes server address information from a local or remote endpoint map. (Management). rpc_mgmt_inq_com_timeout() Returns the communications time-out value in a binding handle. (Client). rpc_mgmt_inq_dflt_protect_level() Returns the default protection level for an authentication service. (Client or server). rpc_mgmt_inq_if_ids() Returns a vector of interface identifiers of interfaces a server offers. (Client, server, or management). rpc_mgmt_inq_server_princ_name() Returns a server's principal name. (Client, server, or management). rpc_mgmt_inq_stats() Returns RPC runtime statistics. (Client, server, or management). rpc_mgmt_is_server_listening() Tells whether a server is listening for remote procedure calls. (Client, server, or management). rpc_mgmt_set_authorization_fn() Establishes an authorization function for processing remote calls to a server's management routines. (Server). rpc_mgmt_set_cancel_timeout() Sets the lower bound on the time to wait before timing out after forwarding a cancel. (Client). rpc_mgmt_set_com_timeout() Sets the communications time-out value in a binding handle. (Client). rpc_mgmt_set_server_stack_size() Specifies the stack size for each server thread. (Server). rpc_mgmt_stats_vector_free() Frees a statistics vector. (Client, server, or management). rpc_mgmt_stop_server_listening() Tells a server to stop listening for remote procedure calls. (Client, server, or management). rpc_network_inq_protseqs() Returns all protocol sequences supported by both the RPC runtime and the operating system. (Client or server). rpc_network_is_protseq_valid() Tells whether the specified protocol sequence is supported by both the RPC runtime and the operating system. (Client or server). rpc_ns_binding_export() Establishes a name service database entry with binding handles or object UUIDs for a server. (Server). rpc_ns_binding_import_begin() Creates an import context for an interface and an object in the name service database. (Client). rpc_ns_binding_import_done() Deletes the import context for searching the name service database. (Client). rpc_ns_binding_import_next() Returns a binding handle of a compatible server (if found) from the name service database. (Client). rpc_ns_binding_inq_entry_name() Returns the name of an entry in the name service database from which the server binding handle came. (Client). rpc_ns_binding_lookup_begin() Creates a lookup context for an interface and an object in the name service database. (Client). rpc_ns_binding_lookup_done() Deletes the lookup context for searching the name service database. (Client). rpc_ns_binding_lookup_next() Returns a list of binding handles of one or more compatible servers (if found) from the name service database. (Client). rpc_ns_binding_select() Returns a binding handle from a list of compatible server binding handles. (Client). rpc_ns_binding_unexport() Removes the binding handles for an interface, or object UUIDs, from an entry in the name service database. (Server). rpc_ns_entry_expand_name() Expands the name of a name service entry. (Client, server, or management). rpc_ns_entry_object_inq_begin() Creates an inquiry context for viewing the objects of an entry in the name service database. (Client, server, or management). rpc_ns_entry_object_inq_done() Deletes the inquiry context for viewing the objects of an entry in the name service database. (Client, server, or management). rpc_ns_entry_object_inq_next() Returns one object at a time from an entry in the name service database. (Client, server, or management). rpc_ns_group_delete() Deletes a group attribute. (Client, server, or management). rpc_ns_group_mbr_add() Adds an entry name to a group; if necessary, creates the entry. (Client, server, or management). rpc_ns_group_mbr_inq_begin() Creates an inquiry context for viewing group members. (Client, server, or management). rpc_ns_group_mbr_inq_done() Deletes the inquiry context for a group. (Client, server, or management). rpc_ns_group_mbr_inq_next() Returns one member name at a time from a group. (Client, server, or management). rpc_ns_group_mbr_remove() Removes an entry name from a group. (Client, server, or management). rpc_ns_import_ctx_add_eval() Adds an evaluation routine to an import context. (Client). rpc_ns_mgmt_binding_unexport() Removes multiple binding handles, or object UUIDs, from an entry in the name service database. (Management). rpc_ns_mgmt_entry_create() Creates an entry in the name service database. (Management). rpc_ns_mgmt_entry_delete() Deletes an entry from the name service database. (Management). rpc_ns_mgmt_entry_inq_if_ids() Returns the list of interfaces exported to an entry in the name service database. (Client, server, or management). rpc_ns_mgmt_free_codesets() Frees a code sets array that has been allocated in memory. (Client). rpc_ns_mgmt_handle_set_exp_age() Sets a handle's expiration age for local copies of name service data. (Client, server, or management). rpc_ns_mgmt_inq_exp_age() Returns the application's global expiration age for local copies of name service data. (Client, server, or management). rpc_ns_mgmt_read_codesets() Reads the code sets attribute associated with an RPC server entry in the name service database. (Client). rpc_ns_mgmt_remove_attribute() Removes an attribute from an RPC server entry in the name service database. (Server, management). rpc_ns_mgmt_set_attribute() Adds an attribute to an RPC server entry in the name service database. (Server, management). rpc_ns_mgmt_set_exp_age() Modifies the application's global expiration age for local copies of name service data. (Client, server, or management). rpc_ns_profile_delete() Deletes a profile attribute. (Client, server, or management). rpc_ns_profile_elt_add() Adds an element to a profile. If necessary, creates the entry. (Client, server, or management). rpc_ns_profile_elt_inq_begin() Creates an inquiry context for viewing the elements in a profile. (Client, server, or management). rpc_ns_profile_elt_inq_done() Deletes the inquiry context for a profile. (Client, server, or management). rpc_ns_profile_elt_inq_next() Returns one element at a time from a profile. (Client, server, or management). rpc_ns_profile_elt_remove() Removes an element from a profile. (Client, server, or management). rpc_object_inq_type() Returns the type of an object. (Server). rpc_object_set_inq_fn() Registers an object inquiry function. (Server). rpc_object_set_type() Assigns the type of an object. (Server). rpc_protseq_vector_free() Frees the memory used by a vector and its protocol sequences. (Client or server). rpc_rgy_get_codesets() Gets supported code sets information from the local host. (Client, server). rpc_rgy_get_max_bytes() Gets the maximum number of bytes that a code set uses to encode one character. (Client, server). rpc_server_inq_bindings() Returns binding handles for communication with a server. (Server). rpc_server_inq_if() Returns the manager entry point vector registered for an interface. (Server). rpc_server_listen() Tells the RPC runtime to listen for remote procedure calls. (Server). rpc_server_register_auth_info() Registers authentication information with the RPC runtime. (Server). rpc_server_register_if() Registers an interface with the RPC runtime. (Server). rpc_server_unregister_if() Unregisters an interface from the RPC runtime. (Server). rpc_server_use_all_protseqs() Tells the RPC runtime to use all supported protocol sequences for receiving remote procedure calls. (Server). rpc_set_local_float_drep() Sets the float type in the runtime to the one with which the application is being compiled. rpc_server_use_all_protseqs_if() Tells the RPC runtime to use all the protocol sequences and endpoints specified in the interface specification for receiving remote procedure calls. (Server). rpc_server_use_protseq() Tells the RPC runtime to use the specified protocol sequence for receiving remote procedure calls. (Server). rpc_server_use_protseq_ep() Tells the RPC runtime to use the specified protocol sequence combined with the specified endpoint for receiving remote procedure calls. (Server). rpc_server_use_protseq_if() Tells the RPC runtime to use the specified protocol sequence combined with the endpoints in the interface specification for receiving remote procedure calls. (Server). rpc_sm_allocate() Allocates memory within the RPC stub memory management scheme. (Usually server, possibly client). rpc_sm_client_free() Frees memory allocated by the current memory allocation and freeing mechanism used by the client stubs. (Client). rpc_sm_destroy_client_context() Reclaims the client memory resources for a context handle, and sets the context handle to NULL. (Client). rpc_sm_disable_allocate() Releases resources and allocated memory within the RPC stub memory management scheme. (Client). rpc_sm_enable_allocate() Enables the stub memory management environment. (Client). rpc_sm_free() Frees memory allocated by the rpc_sm_allocate() routine. (Usually server, possibly client). rpc_sm_get_thread_handle() Gets a thread handle for the stub memory management environment. (Usually server, possibly client). rpc_sm_set_client_alloc_free() Sets the memory allocation and freeing mechanism used by the client stubs. (Client). rpc_sm_set_thread_handle() Sets a thread handle for the stub memory management environment. (Usually server, possibly client). rpc_sm_swap_client_alloc_free() Exchanges the current memory allocation and freeing mechanism used by the client stubs with one supplied by the client. (Client). rpc_string_binding_compose() Combines the components of a string binding into a string binding. (Client or server). rpc_string_binding_parse() Returns, as separate strings, the components of a string binding. (Client or server). rpc_string_free() Frees a character string allocated by the runtime. (Client, server, or management). uuid_compare() Compares two UUIDs and determines their order. (Client, server, or management). uuid_create() Creates a new UUID. (Client, server, or management). uuid_create_nil() Creates a nil UUID. (Client, server, or management). uuid_equal() Determines if two UUIDs are equal. (Client, server, or management). uuid_from_string() Converts a string UUID to its binary representation. (Client, server, or management). uuid_hash() Creates a hash value for a UUID. (Client, server, or management). uuid_is_nil() Determines if a UUID is nil. (Client, server, or management). uuid_to_string() Converts a UUID from a binary representation to a string representation. (Client, server, or management). wchar_t_from_netcs() Converts international character data from a network code set to a local code set. (Client, server). wchar_t_local_size() Calculates the necessary buffer size for a code set conversion from a network code set to a local code set. (Client, server). wchar_t_net_size() Calculates the necessary buffer size for a code set conversion from a local code set to a network code set. (Client, server). wchar_t_to_netcs() Converts international character data from a local code set to a net work code set. (Client, server). 4 Logical_Names The RPC Name Service Interface (NSI) routines uses the following logical names: + RPC_DEFAULT_ENTRY Designates the default entry in the name service database that the import and lookup routines use as the starting point to search for binding information for a compatible server. Normally, the starting entry is a profile. An application that uses a default entry name must define this logical name. The RPC runtime does not provide a default. For example, suppose that a client application needs to search the name service database for a server binding handle. The application can use the rpc_ns_binding_import_begin() routine as part of the search. If so, the application must specify, to the routine's entry_name parameter, the name of the entry in the name service database at which to begin the search. If the search is to begin at the entry that the RPC_DEFAULT_ENTRY logical name specifies, then the application must specify the value NULL to parameter entry_name in rpc_ns_binding_import_begin(). + RPC_DEFAULT_ENTRY_SYNTAX Specifies the syntax of the name provided in the RPC_DEFAULT_ENTRY logical name. In addition, provides the syntax for those RPC NSI routines that allow a default value for the name syntax argument. If the RPC_DEFAULT_ENTRY_SYNTAX logical name is not defined, the RPC runtime uses the rpc_c_ns_syntax_dce name syntax. (For the valid name syntaxes in this reference page and for the valid syntax values, see the table in the description of the frequently used routine argument name_syntax, which appears later in this reference page.) Optionally, each application defines either or both of the first two logical names. The application can change the value of either one, or both, at any time during runtime. 4 RPC_Data_Types_and_Structures The following subsections contain the data types and structures used by client, server, and management application programs. Much of the information in this section is derived from the Application Development Guide. You may want to refer to this book as you read this section. For example, this section contains a brief description of a binding handle. The RPC section of the Application Development Guide explains binding handles in detail. It also explains concepts related to binding handles, such as binding information and string bindings. 5 Binding_Handle A binding handle is a pointer-size opaque variable containing information the RPC runtime uses to manage binding information. The RPC runtime uses binding information to establish a client/ server relationship that allows the execution of remote procedure calls. Based on the context where it is created, a binding handle is considered a server binding handle or a client binding handle. A server binding handle is a reference to the binding information necessary for a client to establish a relationship with a specific server. Many RPC API runtime routines return a server binding handle that you can use to make a remote procedure call. A server binding handle refers to several components of binding information. One is the network address of a server's host system. Each server instance has one or more transport addresses (endpoints). A well-known endpoint is a stable address on the host, while a dynamic endpoint is an address that the RPC runtime requests for the server. Some transport protocols provide fewer well-known endpoints than dynamic endpoints. If binding information contains an endpoint, the corresponding binding handle is a fully bound binding handle. If the information lacks an endpoint, the binding handle is a partially bound binding handle. The RPC runtime creates and provides a client binding handle to a called remote procedure as the handle_t parameter. The client binding handle contains information about the calling client. A client binding handle cannot be used to make a remote procedure call. A server uses the client binding handle. The rpc_binding_server_from_client() routine converts a client binding handle to a server binding handle. You can use the resulting server binding handle to make a remote procedure call. For an explanation of making a remote procedure call with a partially bound binding handle, see the OSF DCE Application Development Guide - Core Components. For an explanation of failures associated with such a call, see the explanation of status code rpc_s_wrong_boot_time in the OSF DCE Problem Determination Guide. Binding information can contain an object UUID. The default object UUID associated with a binding handle is a nil UUID. Clients can obtain a non-nil UUID in various ways, such as from a string representation of binding information (a string binding), or by importing it. The following table contains the RPC runtime routines that operate on binding handles. The table also specifies the type of binding handle, client or server, allowed. Client and Server Binding Handles __________________________________________________________________ Routine Input Argument Output Argument __________________________________________________________________ rpc_binding_copy() Server Server rpc_binding_free() Server None rpc_binding_from_string_binding() None Server rpc_binding_inq_auth_client() Client None rpc_binding_inq_auth_info() Server None rpc_binding_inq_object() Server or client None rpc_binding_reset() Server None rpc_binding_server_from_client() Client Server rpc_binding_set_auth_info() Server None rpc_binding_set_object() Server None rpc_binding_to_string_binding() Server or client None rpc_binding_vector_free() Server None rpc_ns_binding_export() Server None rpc_ns_binding_import_next() None Server rpc_ns_binding_inq_entry_name() Server None rpc_ns_binding_lookup_next() None Server rpc_ns_binding_select() Server Server rpc_server_inq_bindings() None Server If the input argument type is only a client or only a server, the routines return the status code rpc_s_wrong_kind_of_binding when an application provides the incorrect binding handle type. An application can share a single binding handle across multiple threads of execution. The RPC runtime, instead of the application, manages binding handle concurrency control across concurrent remote procedure calls that use a single binding handle. However, the client application has responsibility for binding handle concurrency control for operations that read or modify a binding handle. The related routines are as follows: + rpc_binding_free() + rpc_binding_reset() + rpc_binding_set_auth_info() + rpc_binding_set_object() + rpc_ep_resolve_binding() + rpc_mgmt_set_com_timeout() For example, suppose an application shares a binding handle across two threads of execution and it resets the binding handle endpoint in one of the threads (by calling rpc_binding_reset()). The binding handle in the other thread is then also reset. Similarly, freeing the binding handle in one thread (by calling rpc_binding_free()) frees the binding handle in the other thread. If you do not want this effect, your application can create a copy of a binding handle by calling rpc_binding_copy(). An operation on one binding handle then has no effect on the second binding handle. Clients and servers can access and set object UUIDs using the rpc_binding_inq_object() and rpc_binding_set_object() routines. Routines requiring a binding handle as an argument show a data type of rpc_binding_handle_t. Binding handle arguments are passed by value. 5 Binding_Vector The binding vector data structure contains a list of binding handles over which a server application can receive remote procedure calls. The binding vector contains a count member (count), followed by an array of binding handle (binding_h) elements. The C language representation of a binding vector is as follows: typedef struct { unsigned32 count; rpc_binding_handle_t binding_h[1]; } rpc_binding_vector_t; The RPC runtime creates binding handles when a server application registers protocol sequences. To obtain a binding vector, a server application calls the rpc_server_inq_bindings() routine. A client application obtains a binding vector of compatible servers from the name service database by calling rpc_ns_binding_lookup_next(). In both routines, the RPC runtime allocates memory for the binding vector. An application calls the rpc_binding_vector_free() routine to free the binding vector. An application, when it is finished with an individual binding handle in a binding vector, frees the binding handle by calling rpc_binding_free(). This routine also sets the corresponding pointer in the binding vector to NULL. Note that you should not decrement the count field in a binding vector structure when you call the rpc_binding_free() routine to free an individual binding handle. The following routines require a binding vector and show an argument data type of rpc_binding_vector_t: + rpc_binding_vector_free() + rpc_ep_register() + rpc_ep_register_no_replace() + rpc_ep_unregister() + rpc_ns_binding_export() + rpc_ns_binding_lookup_next() + rpc_ns_binding_select() + rpc_server_inq_bindings() 5 Boolean Routines that require a Boolean-valued argument or return a Boolean value show a data type of boolean32. DCE RPC provides the integer constants TRUE (1) and FALSE (0) for use as Boolean values. 5 Code_Set A code set is a mapping of the members of a character set to specific numeric code values. Different code sets use different numeric code values to represent the same character. In general, operating systems use string names to refer to the code sets that the system supports. It is common for different operating systems to use different string names to refer to the same code set. Distributed applications that run in a network of heterogeneous operating systems need to be able to identify the character sets and code sets that client and server machines are using to avoid losing data during communications between each other. DCE RPC supports transparent automatic conversion for characters that are members of the DCE Portable Character Set (DCE PCS) and which are encoded in the ASCII and U.S. EBCDIC code sets. The RPC runtime automatically converts DCE PCS characters encoded in ASCII or U.S. EBCDIC, if necessary, when they are passed over the network between client and server. DCE RPC applications that need to transfer character data that is outside the DCE PCS character set and ASCII and U.S. EBCDIC encodings (international characters) can use special IDL constructs and a set of DCE RPC routines to set up their applications so that they can pass this "international" character data with minimal or no loss between client and server applications. An example of such an application would be one that used European, Chinese, or Japanese characters mapped to EUC, Big5, or SJIS encodings. Together, the IDL constructs and the DCE RPC routines provide a method of automatic code set conversion for applications that transfer international character data in heterogeneous code set environments. DCE provides a mechanism to uniquely identify a code set; this mechanism is the code set registry. The code set registry assigns a unique identifier to each character set and code set. Because the registry provides code set identifiers that are consistent across a network of heterogeneous operating systems, it provides a method for clients and servers in a heterogeneous environment to use to identify code sets without having to rely on operating system specific string names. The code set data structure contains a 32-bit hexadecimal value (c_set) that uniquely identifies the code set followed by a 16-bit decimal value (c_max_bytes) that indicates the maximum number of bytes this code set uses to encode one character in this code set. The value for c_set is one of the registered values in the code set registry. The following routines require a code set value: + cs_byte_from_netcs() + cs_byte_local_size() + cs_byte_net_size() + cs_byte_to_netcs() + dce_cs_loc_to_rgy() + dce_cs_rgy_to_loc() + rpc_cs_get_tags() + rpc_cs_binding_set_tags() + rpc_rgy_get_max_bytes() + wchar_t_from_netcs() + wchar_t_local_size() + wchar_t_net_size() + wchar_t_to_netcs() In these routines, the code set value shows a data type of unsigned32. The RPC stub buffer sizing routines *Lnet_size() and *_local_size use the value of c_max_bytes to calculate the size of a buffer for code set conversion. The C language representation of a code set structure is as follows: typedef struct { long c_set; short c_max_bytes; } rpc_cs_c_set_t; The code set data structure is a member of the code sets array. 6 Code_Sets_Array The code sets array contains the list of the code sets that a client or server supports. The structure consists of a version number member (version), followed by a count member (count), followed by an array of code set data structures (rpc_cs_c_set_t). This array is declared to be a conformant array so that its size will be determined at runtime. The count member indicates the number of code sets contained in the array. The first element in the code sets array represents the client or server process's local code set. The second element through the nth element represents one or more intermediate code sets that the process can use to transmit character data over the network. Client or server processes can convert into an intermediate code set when their host system does not provide a converter for the other's local code set but does provide a converter for the intermediate code set. DCE RPC routines for character/code sets compatibility evaluation and code set conversion support one intermediate code set, which is the ISO 10646 Universal character/code set. Consequently, DCE requires host systems running applications that transfer international characters to provide converters for this code set. System administrators for machines in internationalized DCE cells (that is, cells of machines that run applications that use the DCE character/code sets compatibility evaluation and conversion functionality) and who want to use other intermediate code sets can run the csrc utility and specify that their intermediate code set(s) be used in preference to ISO 10646. The remaining elements in the array represent other code sets that the process's host supports (that is, code sets for which the system provides converters). The C language representation of a code set structure is as follows: typedef struct rpc_codeset_mgmt_t { unsigned32 version; long count; [size_is(count)] rpc_cs_c_set_t codesets[]; } rpc_codeset_mgmt_t, *rpc_codeset_mgmt_p_t; Client and server applications and DCE RPC routines for automatic code set conversion obtain a code sets array by calling the routine rpc_rgy_get_codesets(). Server applications user the code sets array as input to the rpc_ns_mgmt_set_attribute() routine, which registers their supported code sets in the name service database. Client applications look up a server's supported code sets in the name service database by calling the routine rpc_ns_mgmt_read_codesets() and then use their code sets array to evaluate their supported code sets against the code sets that the server supports. The following DCE RPC routines require a code sets array and show an argument data type of rpc_codeset_mgmt_t: + rpc_ns_mgmt_read_codesets() + rpc_rgy_get_codesets() Server applications that use the routine rpc_ns_mgmt_set_attribute() to register their supported code sets in the name service database also specify the code sets array, but show an argument data type of void. 6 Conversion_Type The conversion type data structure is an enumerated type that RPC stub buffer sizing routines return to indicate whether character data conversion is necessary and whether or not existing storage is sufficient for the stub to store the results of the conversion. The conversion type can be one of the following values: idl_cs_no_convert No code set conversion is required. idl_cs_in_place_convert Code set conversion can be performed in a single storage area. idl_cs_new_buffer_convert The converted data must be written to a new storage area. The C language representation of a conversion type structure is as follows: typedef enum { idl_cs_no_convert, idl_cs_in_place_convert, idl_cs_new_buffer_convert, } idl_cs_convert_t; 5 Endpoint_Map_Inquiry_Handle An endpoint map inquiry handle is a pointer-size opaque variable containing information the RPC runtime uses to access the elements in a local or remote endpoint map. The description of the rpc_ep_register() routine lists the contents of an element. The following routines require an endpoint map inquiry handle and show an argument data type of rpc_ep_inq_handle_t: + rpc_mgmt_ep_elt_inq_begin() + rpc_mgmt_ep_elt_inq_done() + rpc_mgmt_ep_elt_inq_next() 5 Global_Name The Name Service Interface (NSI) uses global names for the names of name service entries. A global name includes both a cell name and a cell-relative name composed of a directory pathname and a leaf name. For a description of global names, see the OSF DCE Administration Guide. The cell name is assigned to a cell root at its creation. When you specify only a cell-relative name to an NSI operation, the NSI automatically expands the name into a global name by inserting the local cell name. Thus, the name of a member in a group or in a profile element is always stored as a global name. When returning the name of a name service entry or a member, NSI operations return global names. For example, even when you specify a cell-relative name as the member_name parameter to routine rpc_ns_group_mbr_add(), when you read that group member (by calling rpc_ns_group_mbr_inq_next()), you will receive the corresponding global name. 5 IDL_Encoding_Service_Handle An IDL encoding service handle is a pointer-size opaque variable that points to functions that control how data encoding or decoding is performed. The following routines return an IDL encoding service handle and show an argument data type of idl_es_handle_t: + idl_es_encode_incremental() + idl_es_decode_buffer() + idl_es_decode_incremental() + idl_es_encode_dyn_buffer() + idl_es_encode_fixed_buffer() The idl_es_handle_free() and idl_es_inq_encoding_id() routines require an IDL encoding service handle. Note that in order to use the IDL encoding services, you must include a header file that has been generated for an application that has used the encode and decode ACF attributes on one or more of its operations. 5 Interface_Handle_and_Specification An interface handle is a pointer-size opaque variable containing information the RPC runtime uses to access the interface specification data structure. The DCE IDL compiler automatically creates an interface specification data structure from each IDL file and creates a global variable of type rpc_if_handle_t for the interface specification. The DCE IDL compiler places an interface handle declaration in the generated interface-name.h file. The compiler generates this include file for each interface. Routines requiring the interface handle as an argument show a data type of rpc_if_handle_t. The form of each interface handle name is as follows: + For the client: if-name_vmajor-version_minor-version_c_ifspec + For the server: if-name_vmajor-version_minor-version_s_ifspec where + The if-name variable is the interface identifier specified in the IDL file. + The major-version variable is the interface's major-version number specified in the IDL file. + The minor-version variable is the interface's minor-version number specified in the IDL file. An example is notes_v1_2_c_ifspec The maximum combined length of the interface identifier and interface version number is 19 characters. Since the major-version and minor-version numbers must each be at least 1 character, the interface name can be no more than 17 characters. This limits the interface handle name to 31 or fewer characters. No concurrency control is required for interface handles. The following routines require an interface handle and show an argument data type of rpc_if_handle_t: + rpc_ep_register() + rpc_ep_register_no_replace() + rpc_ep_resolve_binding() + rpc_ep_unregister() + rpc_if_inq_id() + rpc_ns_binding_export() + rpc_ns_binding_import_begin() + rpc_ns_binding_lookup_begin() + rpc_ns_binding_unexport() + rpc_server_inq_if() + rpc_server_register_if() + rpc_server_unregister_if() + rpc_server_use_all_protseqs_if() + rpc_server_use_protseq_if() 5 Interface_Identifier The interface identifier (id) data structure contains the interface UUID and major-version and minor-version numbers of an interface. The interface identifier is a subset of the data contained in the interface specification structure. The C language representation of an interface identifier structure is as follows: typedef struct { uuid_t uuid; unsigned16 vers_major; unsigned16 vers_minor; } rpc_if_id_t; Routines that require an interface identifier structure show a data type of rpc_if_id_t. In those routines, the application is responsible for providing memory for the structure. The rpc_if_inq_id() routine returns the interface identifier from an interface specification. The following routines require an interface identifier: + rpc_mgmt_ep_elt_inq_begin() + rpc_mgmt_ep_elt_inq_next() + rpc_mgmt_ep_unregister() + rpc_ns_mgmt_binding_unexport() + rpc_ns_profile_elt_add() + rpc_ns_profile_elt_inq_begin() + rpc_ns_profile_elt_inq_next() + rpc_ns_profile_elt_remove() 5 Interface_Identifier_Vector The interface identifier (id) vector data structure contains a list of interfaces offered by a server. The interface identifier vector contains a count member (count), followed by an array of pointers to interface identifiers (rpc_if_id_t). The C language representation of an interface identifier vector is as follows: typedef struct { unsigned32 count; rpc_if_id_t *if_id[1]; } rpc_if_id_vector_t; The interface identifier vector is a read-only vector. To obtain a vector of the interface identifiers registered by a server with the RPC runtime, an application calls the rpc_mgmt_inq_if_ids() routine. To obtain a vector of the interface identifiers exported by a server to a name service database, an application calls the rpc_ns_mgmt_entry_inq_if_ids() routine. The RPC runtime allocates memory for the interface identifier vector. The application calls the rpc_if_id_vector_free() routine to free the interface identifier vector. 5 Manager_Entry_Point_Vector The manager Entry Point Vector (EPV) is an array of pointers to remote procedures. The DCE IDL compiler automatically generates a manager EPV data type, into the header file generated by the IDL compiler, for use in constructing manager EPVs. The data type is named as follows: if-name_vmajor-version_minor-version_epv_t where + The if-name variable is the interface identifier specified in the IDL file. + The major-version variable is the interface's major-version number specified in the IDL file. + The minor-version variable is the interface's minor-version number specified in the IDL file. By default, the DCE IDL compiler automatically creates and initializes a manager EPV. DCE IDL creates this EPV assuming that a manager routine of the same name exists for each procedure in the interface (as specified in the IDL file). The DCE IDL compiler can define a client Entry Point Vector with addresses of local routines. Client applications can call these routines. For more information about client entry point vectors, see the explanation of the -cepv argument in the idl reference page. If the server offers multiple implementations of the same interface, the server must create additional manager EPVs, one for each implementation. Each EPV must contain exactly one entry point (address of a function) for each procedure defined in the IDL file. The server application declares and initializes one manager EPV variable of type if-name_vmajor-version_minor-version_epv_t for each implementation of the interface. The rpc_server_register_if() and rpc_server_inq_if() routines use the manager EPV data type and show the manager EPV argument as having an rpc_mgr_epv_t data type. 5 Name_Service_Handle A name service handle is a pointer-size opaque variable containing information the RPC runtime uses to return the following RPC data from the name service database: + Server binding handles + UUIDs of resources offered by a server + Profile members + Group members The following routines require a name service handle and show an argument data type of rpc_ns_handle_t: + rpc_ns_binding_import_begin() + rpc_ns_binding_import_next() + rpc_ns_binding_import_done() + rpc_ns_binding_lookup_begin() + rpc_ns_binding_lookup_next() + rpc_ns_binding_lookup_done() + rpc_ns_entry_object_inq_begin() + rpc_ns_entry_object_inq_next() + rpc_ns_entry_object_inq_done() + rpc_ns_group_mbr_inq_begin() + rpc_ns_group_mbr_inq_next() + rpc_ns_group_mbr_inq_done() + rpc_ns_profile_elt_inq_begin() + rpc_ns_profile_elt_inq_next() + rpc_ns_profile_elt_inq_done() + rpc_ns_mgmt_handle_set_exp_age() The scope of a name service handle is from a *_begin() routine through the corresponding *_done() routine. Applications have responsibility for concurrency control of name service handles across threads. 5 Protocol_Sequence A protocol sequence is a character string identifying the network protocols used to establish a relationship between a client and server. The protocol sequence contains a set of options that the RPC runtime must know about. The following options are in this set: + The RPC protocol used for communications (choices are ncacn and ncadg). + The format used in the network address supplied in the binding (choice is ip). + The transport protocol used for communications (choices are tcp and udp). Because only certain combinations of these options are valid (are useful for interoperation), RPC provides predefined strings that represent the valid combinations. RPC applications use only these strings. The following table contains predefined strings representing valid protocol sequences. In the descriptions NCA is an abbreviation of Network Computing Architecture. Valid Protocol Sequences ___________________________________________________________ Protocol Sequence Description ___________________________________________________________ ncacn_ip_tcp NCA Connection over Internet Protocol: Transmission Control Protocol ip or ncadg_ip_udp NCA Datagram over Internet Protocol: User Datagram Protocol ncacn_dnet_nsp NCA Connection over DECnet Phase IV ncacn_osi_dna NCA Connection over DECnet/OSI A server application can use a particular protocol sequence only if the operating system software supports that protocol. A server chooses to accept remote procedure calls over some or all of the supported protocol sequences. Client and server applications can determine if a protocol sequence is supported by both the RPC runtime and the operating system. The applications make this determination by calling the following routines: + rpc_network_inq_protseqs() + rpc_network_is_protseq_valid() The following routines allow server applications to register protocol sequences with the runtime: + rpc_server_use_all_protseqs() + rpc_server_use_all_protseqs_if() + rpc_server_use_protseq() + rpc_server_use_protseq_ep() + rpc_server_use_protseq_if() Those routines requiring a protocol sequence argument show a data type of unsigned_char_t *. A client can use the protocol sequence strings to construct a string binding using the rpc_string_binding_compose() routine. 5 Protocol_Sequence_Vector The protocol sequence vector data structure contains a list of protocol sequences over which the RPC runtime can send or receive remote procedure calls. The protocol sequence vector contains a count member (count), followed by an array of pointers to protocol sequence strings (protseq). The C language representation of a protocol sequence vector is as follows: typedef struct { unsigned32 count; unsigned_char_t *protseq[1]; } rpc_protseq_vector_t; The protocol sequence vector is a read-only vector. To obtain a protocol sequence vector, a server application calls the rpc_network_inq_protseqs() routine. The RPC runtime allocates memory for the protocol sequence vector. The server application calls the rpc_protseq_vector_free() routine to free the protocol sequence vector. 5 Statistics_Vector The statistics vector data structure contains statistics from the RPC runtime on a per address space basis. The statistics vector contains a count member (count), followed by an array of statistics. Each array element contains an unsigned32 value. The following list describes the statistics indexed by the specified constant: rpc_c_stats_calls_in The number of remote procedure calls received by the runtime. rpc_c_stats_calls_out The number of remote procedure calls initiated by the runtime. rpc_c_stats_pkts_in The number of network packets received by the runtime. rpc_c_stats_pkts_out The number of network packets sent by the runtime. The C language representation of a statistics vector is as follows: typedef struct { unsigned32 count; unsigned32 stats[1]; } rpc_stats_vector_t; To obtain runtime statistics, an application calls the rpc_mgmt_inq_stats() routine. The RPC runtime allocates memory for the statistics vector. The application calls the rpc_mgmt_stats_vector_free() routine to free the statistics vector. 5 String_Binding A string binding contains the character representation of a binding handle. String bindings are a convenient way of representing portions of a binding handle. However, you cannot use string bindings directly to make remote procedure calls. You must first call the routine rpc_binding_from_string_binding(), which converts a string binding to a binding handle. A string binding does not contain all the information from a binding handle. For example, a call to the routine rpc_binding_to_string_binding() does not translate the authenti- cation information sometimes associated with a binding handle into the resulting string binding. You can begin the development of a distributed application by having its servers communicate their binding information to clients by using string bindings. This communication allows a server to establish a client/server relationship without using the local endpoint map or the name service database. In this case, the server calls none of the rpc_ep_register(), rpc_ep_register_no_replace(), and rpc_ns_binding_export() routines. Instead, the server calls only routine rpc_server_inq_bindings() to obtain a vector of binding handles. The server obtains binding handles one at a time from the vector and calls routine rpc_binding_to_string_binding() to convert each binding handle into a string binding. The resulting string binding is always fully bound and may contain a non-nil object UUID. The server then makes some or all of its string bindings available to clients. One way is placing the string bindings in a file to be read by clients or users or both. Another way is delivering the string bindings to clients or users by means of a file, mail, or paper. You can continue the distributed application's development by changing the application so that servers use the local endpoint map and the name service database to communicate their binding information. To find the server, a client obtains a string binding containing a protocol sequence that the client runtime supports and, optionally, an object UUID that the client requires. The client then calls routine rpc_binding_from_string_binding() to convert the string binding into a server binding handle. Other useful routines for working with string bindings are rpc_string_binding_compose(), which creates a string binding from its component parts, and rpc_string_binding_parse(), which separates a string binding into its component parts. The two formats of a string binding follow. The four fields represent the object UUID, RPC protocol sequence, network address, and endpoint and network options of the binding. A delimiter character such as @ (at sign) or : (colon) separates each field. A string binding does not contain any white space. object-uuid @ rpc-protocol-sequence : nw-addr [endpoint, option ...] or object-uuid @ rpc-protocol-sequence : nw-addr [endpoint = endpoint, option ...] object-uuid This field specifies the UUID of the object operated on by the remote procedure that is called with this string binding. The RPC runtime, at the server, maps the object's type to a manager Entry Point Vector (EPV) to invoke the correct manager routine. The explanation of the routine rpc_server_register_if() discusses mapping object UUIDs to manager EPVs. This field is optional. If you do not provide it the RPC runtime assumes a nil UUID. @ This symbol is the delimiter character for the object UUID field. If you specify an object UUID you must follow it with this symbol. rpc-protocol-sequence This field specifies the protocol sequence used for making remote procedure calls. The valid protocol sequences are as follows: ncacn_ip_tcp ncadg_ip_udp More information about these valid protocol sequences appears in the table in the entry on Protocol_Sequence. This field is required. : This symbol is the delimiter character for the RPC protocol sequence field. nw-addr This field specifies the address (addr) of a host on a network (nw) that receives remote procedure calls made with this string binding. The format and content of the network address depends on the value of rpc-protocol- sequence as follows: ncacn_ip_tcp and ncadg_ip_udp Specify an Internet address using the common Internet address notation or hostname. Two examples with common Internet address notation are 128.10.2.30 and #126.15.1.28. The second example shows the use of the optional # (number sign) character. An example with a host name is ko. If the specified hostname is multihomed, the binding handle returned from routine rpc_binding_from_string_binding() contains a host address. It is the first host address returned from the system library call that translates a hostname to a host address for the network address format in the protocol sequence. To control the host address used, specify the network address using the common Internet address notation instead of a hostname. The network address field is optional. If you do not supply this field, the string binding refers to your local host. [ This symbol is the delimiter character specifying that one endpoint and zero or more options follow. If the string binding contains at least one endpoint, this symbol is required. endpoint This field specifies the endpoint, or address of a specific server instance on a host, to receive remote procedure calls made with this string binding. Optionally the keyword endpoint= can precede the endpoint specifier. The format and content of the endpoint depends on the specified protocol sequence as follows: ncacn_ip_tcp and ncadg_ip_udp Specify an Internet port number. An example of an Internet port number is 1025. The endpoint field is optional. For more information about endpoints, see the information on binding handles in this reference page. , This symbol is the delimiter character specifying that option data follows. If an option follows, this delimiter is required. option This field specifies any options. Each option is specified as option name=option value. The format and content of the option depends on the specified protocol sequence as follows: ncacn_ip_tcp and ncadg_ip_udp There are no Internet options. The option field is optional. ] This symbol is the delimiter character specifying that one endpoint and zero or more options precede. If the string binding contains at least one endpoint, this symbol is required. The \ (backslash) character is treated as an escape character for all string binding fields. Examples of valid string bindings follow. In each example obj-uuid represents a UUID in string form. In other words, the symbol obj-uuid can represent the UUID 308fb580-1eb2-11ca-923b-08002b1075a7. obj-uuid@ncacn_ip_tcp:16.20.16.27[2001] obj-uuid@ncacn_ip_tcp:16.20.16.27[endpoint=2001] 6 String_UUID A string UUID contains the character representation of a UUID. A string UUID consists of multiple fields of hexadecimal characters. Each field has a fixed length, and dashes separate the fields. An example of a string UUID follows: 989c6e5c-2cc1-11ca-a044-08002b1bb4f5 When you supply a string UUID as an input argument to an RPC runtime routine, you can enter the alphabetic hexadecimal characters in either uppercase or lowercase letters. The RPC runtime routines that return a string UUID always return the hexadecimal characters in lowercase letters. The following routines require a string UUID: + rpc_string_binding_compose() + uuid_from_string() The following routines return a string UUID: + rpc_string_binding_parse() + uuid_to_string() 6 Unsigned_Character_String DCE RPC treats all characters in strings as unsigned characters. Those routines with character string arguments show a data type of unsigned_char_t *. 6 UUID_Vector The UUID vector data structure contains a list of UUIDs. The UUID vector contains a count member (count), followed by an array of pointers to UUIDs. The C language representation of a UUID vector is as follows: typedef struct { unsigned32 count; uuid_t *uuid[1]; } uuid_vector_t; An application constructs a UUID vector to contain object UUIDs to be exported or unexported from the name service database. The following routines require a UUID vector and show an argument data type of uuid_vector_t: + rpc_ep_register() + rpc_ep_register_no_replace() + rpc_ep_unregister() + rpc_ns_binding_export() + rpc_ns_binding_unexport() + rpc_ns_mgmt_binding_unexport() 4 Permissions_Required To use the Name Service Interface (NSI) routines to access entries in a Cell Directory Service (CDS) database, you need Access Control List (ACL) permissions. Depending on the NSI operation, you need ACL permissions to the parent directory or the CDS object entry (the name service entry) or both. The ACL permissions are as follows: + To create an entry, you need insert permission to the parent directory. + To read an entry, you need read permission to the CDS object entry. + To write to an entry, you need write permission to the CDS object entry. + To delete an entry, you need delete permission either to the CDS object entry or to the parent directory. + To test an entry, you need either test permission or read permission to the CDS object entry. Note that write permission does not imply read permission. To find the ACL permissions for the NSI routines whose names begin with rpc_ns, see these routines' reference pages. The non-NSI routines whose names do not begin with rpc_ns do not need ACL permissions, so their reference pages do not specify any. 4 Frequently_Used_Routine_Parameters A few parameters are common to many of the DCE RPC routines. These parameters are described fully here and again briefly on the specific routine reference pages. 5 binding Used as an input or output parameter. Returns a binding handle for making remote procedure calls to a server. A client obtains a binding handle by calling one of the following routines: + rpc_binding_copy() + rpc_binding_from_string_binding() + rpc_ns_binding_import_next() + rpc_ns_binding_select() Creating a binding handle establishes a relationship between a client and a server. However, the relationship does not involve any communications between the client and server. The communications occur when a client makes a remote procedure call. As an input parameter to a remote procedure call, binding specifies a binding handle that refers to binding information. The client's RPC runtime uses this binding information to make a remote procedure call to a server. Server manager routines can extract client information from a client binding handle by using the following routines: + rpc_binding_inq_auth_client() + rpc_binding_inq_object() + rpc_binding_to_string_binding() + rpc_string_binding_parse() 5 name Used as an input/output parameter. When used as an input parameter, the value of this parameter depends on the syntax selected in the name_syntax parameter. If it is allowed by the called routine, the value NULL specifies that the routine uses the name specified in the RPC_DEFAULT_ENTRY environment variable. Specifying NULL also has the called routine use the name syntax that the environment variable RPC_DEFAULT_ENTRY_SYNTAX specifies. For a name_syntax value of rpc_c_ns_syntax_dce, use the DCE naming rules to specify parameter name. As an output parameter, returns an entry in the name service database in the form of a character string that includes a terminating null character. The value of this parameter depends on the syntax selected in name_syntax. For a name_syntax value of rpc_c_ns_syntax_dce, name is returned using the DCE naming syntax. The DCE RPC runtime allocates memory for the returned string. The application is responsible for calling the rpc_string_free() routine to deallocate the string. If an application does not want a returned name string, the application usually specifies NULL for this parameter. The one exception is routine rpc_ns_entry_expand_name(); it always returns a name string. 5 name_syntax Used as an input parameter, an integer value that specifies the syntax of an entry name. When allowed by the called routine, a value of rpc_c_ns_syntax_default specifies that the routine uses the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX environment variable. The following table lists the valid syntaxes that applications can use in DCE RPC for entries in the name service database. Valid Name Syntaxes ________________________________________________ Constant Value Description ________________________________________________ rpc_c_ns_syntax_default 0 Default syntax rpc_c_ns_syntax_dce 3 DCE The name_syntax parameter tells routines how to parse the entry name specified in an input name parameter or specifies the syntax to use when returning an entry name as an output name parameter. If the RPC_DEFAULT_ENTRY_SYNTAX environment variable is not defined, the RPC runtime uses the rpc_c_ns_syntax_dce name syntax. 5 string Used as an input or output parameter. Returns a character string, which always includes the terminating null character \0. The DCE RPC runtime allocates memory for the returned string. The application calls the rpc_string_free() routine to deallocate the memory occupied by the string. If there is no data for the requested string, the routine returns the string \0. For example, if the string binding passed to routine rpc_string_binding_parse() does not contain an object UUID, the routine returns \0 as the value of the object UUID string. The application must call the rpc_string_free() routine to deallocate the memory occupied by this string. If an application does not require a returned output string, the application specifies NULL for this parameter. 5 status Each routine in the RPC API returns a DCE status code indicating whether the routine completed successfully or, if not, why not. A return value of rpc_s_ok indicates success. All other return values signify routine failure. The status codes listed for each RPC runtime routine are the most likely, but not necessarily all, the status codes that the routine can return. The status code argument has a data type of unsigned32. To translate a DCE status code to a text message, call the routine dce_error_inq_text(). Note that RPC exceptions are equivalent to RPC status codes. To identify the status code that corresponds to a given exception, replace the _x_ string of the exception with the string _s_; for example, the exception rpc_x_already_listening is equivalent to the status code rpc_s_already_listening. For more information about the RPC status codes, see the OSF DCE Problem Determination Guide. 5 uuid Used as an input or output parameter. When you need to specify a nil UUID to a uuid input parameter in any of the DCE RPC routines, you can supply the value NULL. 4 RELATED_INFORMATION Books: OSF DCE Application Development Guide-Introduction & Style Guide OSF DCE Application Development Guide-Core Components OSF DCE Application Development Guide-Directory Services OSF DCE Command Reference 3 Application_Routines These are the RPC application development routines. 4 cs_byte_from_netcs NAME cs_byte_from_netcs - Converts international character data from a network code set to a local code set Used by client and server applications. SYNOPSIS #include void cs_byte_from_netcs( rpc_binding_handle_t binding, unsigned32 network_code_set_value, idl_byte *network_data, unsigned32 network_data_length, unsigned32 local_buffer_size, idl_byte *local_data, unsigned32 *local_data_length, error_status_t *status ); PARAMETERS Input binding Specifies the target binding handle from which to obtain code set conversion information. When called from the client stub, this value is the binding handle of a compatible server returned by the rpc_ns_binding_import_next() or rpc_ns_binding_select() routine. When called from the server stub, this value is a pointer to binding information that the client stub passed in the RPC call. network_code_set_value The registered hexadecimal integer value that represents the code set that was used to transmit character data over the network. In general, the network'' code set is the code set that the client application's code sets evaluation routine has determined to be compatible for this client and server. When the caller is the client stub, this value is the receiving tag. When the caller is the server stub, this value is the sending tag. network_data A pointer to the international character data that has been received, in the network code set encoding. network_data_length The number of idl_byte data elements to be converted. For a varying array or a conformant varying array, this value is the local value of the length_is variable. For a conformant array, this value is the local value of the size_is variable. For a fixed array, the value is the array size specified in the interface definition. local_buffer_size A pointer to the buffer size to be allocated to contain the converted data, in units of byte. The value specified in this parameter is the local buffer size returned from the cs_byte_local_size() routine. Output local_data A pointer to the converted data, in idl_byte format. local_data_length The length of the converted data, in units of idl_byte. Specify NULL if a fixed array is to be converted. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_ss_incompatible_codesets The specified code set does not match the code set specified in the sending tag in the binding handle. If this error occurs in the server stub, an exception is raised to the client application. When running the host converter, the following errors can occur: rpc_s_ss_invalid_char_input rpc_s_ss_short_conv_buffer rpc_s_ss_iconv_error (HP-UX reference platform only) rpc_s_ss_no_memory (HP-UX reference platform only) When invoked from the server stub, the routine calls the dce_cs_loc_to_rgy() routine and the host converter routines. If these routines return an error, an exception is raised to the client application. DESCRIPTION The cs_byte_from_netcs() routine belongs to a set of DCE RPC routines for use by client and server applications that are transferring international character data in a heterogeneous character set and code sets environment. The cs_byte_from_netcs() routine is one of the DCE RPC stub code set conversion routines that RPC stubs use before they marshall or unmarshall data to convert international character data to and from local and network code sets. Client and server stubs call the cs_byte_*_netcs() routines when the cs_byte type has been specified as the local data type using the cs_char attribute in the attribute configuration file for the application. (the cs_byte type is equivalent to the byte type.) Client and server stubs call the cs_byte_from_netcs() routine before they unmarshall the international character data received from the network. The routine takes a binding handle, a code set value that identifies the code set used to transfer international character data over the network, the address of the network data, in idl_byte format, that may need to be converted, and the data length, in units of idl_byte. The routine compares the sending code set to the local code set currently in use. If the routine finds that code set conversion is necessary, (because the local code set differs from the code set specified to be used on the network), it determines which host code set converter to call to convert the data and then invokes that converter. The routine then returns the converted data, in idl_byte format. If the data is a varying, conformant, or conformant varying array, the routine also returns the length of the converted data, in units of idl_byte. Applications can specify local data types other than cs_byte and wchar_t (the local data types for which DCE RPC supplies stub code set conversion routines) with the cs_char ACF attribute. In this case, the application must also supply local_type_to_netcs() and local_type_from_netcs() stub conversion routines for this type. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: wchar_t_from_netcs cs_byte_to_netcs wchar_t_to_netcs 4 cs_byte_local_size NAME cs_byte_local_size - Calculates the necessary buffer size for code set conversion from a network code set to a local code set Used by client and server applications. SYNOPSIS #include void cs_byte_local_size( rpc_binding_handle_t binding, unsigned32 network_code_set_value, unsigned32 network_buffer_size, idl_cs_convert_t *conversion_type, unsigned32 *local_buffer_size, error_status_t *status ); PARAMETERS Input binding Specifies the target binding handle from which to obtain buffer size evaluation information. When called from the client stub, this value is the binding handle of a compatible server returned by the rpc_ns_binding_import_next() or rpc_ns_binding_select() routine. When called from the server stub, this value is a pointer to binding information that the client stub passed in the RPC call. network_code_set_value The registered hexadecimal integer value that represents the code set used to transmit character data over the network. In general, the "network" code set is the code set that the client application's code sets evaluation routine has determined to be compatible for this client and server. When the caller is the client stub, this value is the receiving tag. When the caller is the server stub, this value is the sending tag. network_buffer_size The size, in units of idl_byte, of the buffer that is allocated for the international character data. For a conformant or conformant varying array, this value is the network value of the size_is variable for the array; that is, the value is the size of the unmarshalled string if no conversion is done. Output conversion_type A pointer to the enumerated type defined in dce/idlbase.h that indicates whether data conversion is necessary and whether or not the existing buffer is sufficient for storing the results of the conversion. The conversion type can be one of the following values: idl_cs_no_convert No code set conversion is required. idl_cs_in_place_convert Code set conversion can be performed in the current buffer. idl_cs_new_buffer_convert The converted data must be written to a new buffer. local_buffer_size A pointer to the buffer size that needs to be allocated to contain the converted data, in units of idl_byte. This value is to be used as the local value of the size_is variable for the array, and is non-NULL only if a conformant or conformant varying array is to be unmarshalled. A value of NULL in this parameter indicates that a fixed or varying array is to be unmarshalled. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_ss_incompatible_codesets The specified code set does not match the code set specified in the sending tag in the binding handle. If this error occurs in the server stub, an exception is raised to the client application. When invoked from the server stub, this routine calls the routines dce_cs_loc_to_rgy() and rpc_rgy_get_max_bytes(). If either of these routines returns an error, the cs_byte_local_size() routine raises an exception to the client application. DESCRIPTION The cs_byte_local_size() routine belongs to a set of DCE RPC routines for use by client and server applications that are transferring international character data in a heterogeneous character set and code sets environment. The cs_byte_local_size() routine is one of the DCE RPC buffer sizing routines that RPC stubs use before they marshall or unmarshall data to determine whether or not the buffers allocated for code set conversion need to be enlarged to hold the converted data. The buffer sizing routines determine the type of conversion required and calculate the size of the necessary buffer (if a new one is required); the RPC stub then allocates a buffer of that size before it calls one of the code set conversion routines. Client and server stubs call the cs_byte_*_size routines when the cs_byte type has been specified as the local data type using the cs_char attribute in the attribute configuration file for the application. Applications do not call cs_byte_local_size() routine directly. Client and server stubs call the routine before they unmarshall any data. The stubs pass the routine a binding handle and a code set value that identifies the code set that was used to transfer international character data over the network. The stubs also specify the network storage size of the data, in units of idl_byte, if a conformant or conformant varying array is to be unmarshalled, or they specify NULL if a fixed or varying array is to be marshalled. When called from a client stub, the cs_byte_local_size() routine determines the value of conversion_type from the client and server's code set tag information stored in the binding handle by a code sets evaluation routine or a tag-setting routine. If the conversion type specified in the handle is idl_cs_new_buffer_convert, the routine sets the conversion_type parameter to this value and, if a conformant or conformant varying array is to be unmarshalled, calculates a new buffer size by multiplying the value of local_buffer_size by the c_max_bytes value for the code set specified in network_code_set_value. The routine returns the new buffer size in the local_buffer_size parameter. The size is specified in units of cs_byte, which is the local representation used for international character data (and is equivalent to the byte data type). For fixed and varying arrays, the routine assumes that network_buffer_size is sufficient to store the converted data. If the handle information specifies idl_cs_convert_in_place or idl_cs_no_convert, the routine assumes that network_buffer_size can store the converted data (or that no conversion is necessary) and returns idl_cs_convert_in_place (or idl_cs_no_convert) in the conversion_type parameter. The routine also returns the value of network_buffer_size in local_buffer_size if a conformant or conformant varying array is to be marshalled. In cases where the binding handle does not contain the results of character and code sets evaluation, or where it is being called from the server stub, the cs_byte_local_size() routine determines the value of conversion_type itself using the local code set value and the code set value passed in the network_code_set_value parameter and returns the appropriate conversion_type value. If a conformant or conformant varying array is to be unmarshalled, and the routine finds that a new buffer is required to hold the converted data, the routine calculates the size of this new buffer (by multiplying the value of network_buffer_size by the local code set c_max_bytes value) and returns the results, in units of cs_byte, in local_buffer_size. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: cs_byte_net_size wchar_t_local_size wchar_t_net_size 4 cs_byte_net_size NAME cs_byte_net_size - Calculates the necessary buffer size for code set conversion from a local code set to a network code set Used by client and server applications. SYNOPSIS #include void cs_byte_net_size( rpc_binding_handle_t binding, unsigned32 network_code_set_value, unsigned32 local_buffer_size, idl_cs_convert_t *conversion_type, unsigned32 *network_buffer_size, error_status_t *status ); PARAMETERS Input binding Specifies the target binding handle from which to obtain buffer size evaluation information. When called from the client stub, this value is the binding handle of a compatible server returned by the rpc_ns_binding_import_next() or rpc_ns_binding_select() routine. When called from the server stub, this value is a pointer to binding information that the client stub passed in the RPC call. network_code_set_value The registered hexadecimal integer value that represents the code set to be used to transmit character data over the network. In general, the "network" code set is the code set that the client application's code sets evaluation routine has determined to be compatible for this client and server. When the caller is the client stub, this value is the sending tag. When the caller is the server stub, this value is the receiving tag. local_buffer_size The size, in units of idl_byte, of the buffer that is allocated for the international character data. This value is the local value of the size_is variable for the array; that is, the value is the size of the marshalled string if no conversion is done. Output conversion_type A pointer to the enumerated type defined in dce/idlbase.h that indicates whether data conversion is necessary and whether or not existing storage is sufficient for storing the results of the conversion. The conversion type can be one of the following values: idl_cs_no_convert No code set conversion is required. idl_cs_in_place_convert Code set conversion can be performed in the current buffer. idl_cs_new_buffer_convert The converted data must be written to a new buffer. network_buffer_size A pointer to the buffer size that needs to be allocated to contain the converted data, in units of idl_byte. This value is to be used as the network value of the size_is variable for the array, and is non-NULL only if a conformant or conformant varying array is to be marshalled. A value of NULL in this parameter indicates that a fixed or varying array is to be marshalled. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_ss_incompatible_codesets The specified code set does not match the code set specified in the sending tag in the binding handle. If this error occurs in the server stub, an exception is raised to the client application. When invoked from the server stub, this routine calls the routines dcs_cs_loc_to_rgy() and rpc_rgy_get_max_bytes(). If either of these routines returns an error, the cs_byte_net_size() routine raises an exception to the client application. DESCRIPTION The cs_byte_net_size() routine belongs to a set of DCE RPC routines for use by client and server applications that are transferring international character data in a heterogeneous character set and code sets environment. The cs_byte_net_size() routine is one of the DCE RPC buffer sizing routines that RPC stubs use before they marshall or unmarshall data to determine whether or not the buffers allocated for code set conversion need to be enlarged to hold the converted data. The buffer sizing routines determine the type of conversion required and calculate the size of the necessary buffer (if a new one is required). The RPC stub then allocates a buffer of that size before it calls one of the code set conversion routines. Client and server stubs call the cs_byte_*_size routines when the cs_byte type (which is equivalent to byte) has been specified as the local data type using the cs_char attribute in the attribute configuration file for the application. Applications do not call the cs_byte_net_size() routine directly. Client and server stubs call the routine before they marshall any data. The stubs pass the routine a binding handle and a code set value that identifies the code set to be used to transfer international character data over the network. The stubs also specify the local storage size of the data, in units of byte. When called from a client stub, the cs_byte_net_size() routine determines the value of conversion_type from the client and server's code set tag information set up the binding handle by a code sets evaluation routine or a tag-setting routine. If the conversion type specified in the handle is idl_cs_new_buffer_convert, the routine sets the conversion_type parameter to this value and, if a conformant or conformant varying array is to be marshalled, calculates a new buffer size by multiplying the value of local_buffer_size by the c_max_bytes value for the code set specified in network_code_set_value (the sending tag parameter). The routine returns the new buffer size in the network_buffer_size parameter. The size is specified in units of cs_byte, which is the network representation used for international character data (and is equivalent to the byte type). For fixed and varying arrays, the routine assumes that local_buffer_size is sufficient to store the converted data. If the handle information specifies idl_cs_convert_in_place or idl_cs_no_convert, the routine assumes that local_buffer_size can store the converted data (or that no conversion is necessary) and returns idl_cs_convert_in_place (or idl_cs_no_convert) in the conversion_type parameter. The routine also returns the value of local_buffer_size in network_buffer_size if a conformant or conformant varying array is to be marshalled. In cases where the binding handle does not contain the results of character and code sets evaluation, or where it is being called from the server stub, the cs_byte_net_size() routine determines the value of conversion_type itself using the local code set value and the code set value passed in the network_code_set_value parameter and returns the appropriate conversion_type value. If a conformant or conformant varying array is to be marshalled, and the routine finds that a new buffer is required to hold the converted data, the routine calculates the size of this new buffer (by multiplying the value of local_buffer_size by the network code set c_max_bytes value) and returns the results, in units of cs_byte, in network_buffer_size. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: cs_byte_local_size wchar_t_local_size wchar_t_net_size 4 cs_byte_to_netcs NAME cs_byte_to_netcs - Converts international character data from a local code set to a network code set Used by client and server applications. SYNOPSIS #include void cs_byte_to_netcs( rpc_binding_handle_t binding, unsigned32 network_code_set_value, idl_byte *local_data, unsigned32 local_data_length, idl_byte *network_data, unsigned32 *network_data_length, error_status_t *status ); PARAMETERS Input binding Specifies the target binding handle from which to obtain code set conversion information. When called from the client stub, this value is the binding handle of a compatible server returned by the rpc_ns_binding_import_next() or rpc_ns_binding_select() routine. When called from the server stub, this value is a pointer to binding information that the client stub passed in the RPC call. network_code_set_value The registered hexadecimal integer value that represents the code set to be used to transmit character data over the network. In general, the network'' code set is the code set that the client application's code sets evaluation routine has determined to be compatible for this client and server. When the caller is the client stub, this value is the sending tag. When the caller is the server stub, this value is the receiving tag. local_data A pointer to the international character data to be transmitted, in the local code set encoding. local_data_length The number of idl_byte data elements to be converted. For a varying array or a conformant varying array, this value is the local value of the length_is variable. For a conformant array, this value is the local value of the size_is variable. For a fixed array, the value is the array size specified in the interface definition. Output network_data A pointer to the converted data, in units of idl_byte. network_data_length A pointer to the length of the converted data, in units of idl_byte. Specify NULL if a fixed or conformant array is to be converted. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_ss_incompatible_codesets The specified code set does not match the code set specified in the sending tag in the binding handle. If this error occurs in the server stub, an exception is raised to the client application. When running the host converter, the following errors can occur: rpc_s_ss_invalid_char_input rpc_s_ss_short_conv_buffer rpc_s_ss_iconv_error (HP-UX reference platform only) rpc_s_ss_no_memory (HP-UX reference platform only) When invoked from the server stub, the routine calls the dce_cs_loc_to_rgy() routine and the host converter routines. If these routines return an error, an exception is raised to the client application. DESCRIPTION The cs_byte_to_netcs() routine belongs to a set of DCE RPC routines for use by client and server applications that are transferring international character data in a heterogeneous character set and code sets environment. The cs_byte_to_netcs() routine is one of the DCE RPC stub code set conversion routines that RPC stubs use before they marshall or unmarshall data to convert international character data to and from local and network code sets. Client and server stubs call the cs_byte_*_netcs() routines when the cs_byte type has been specified as the local data type using the cs_char attribute in the attribute configuration file for the application. (The cs_byte type is equivalent to the byte type.) Client and server stubs call the cs_byte_to_netcs() routine before they marshall any data. The routine takes a binding handle, a code set value that identifies the code set to be used to transfer international character data over the network, the address of the data to be converted, and the length of the data to be converted, in units of idl_byte. The routine compares the code set specified as the network code set to the local code set currently in use. If the routine finds that code set conversion is necessary, (because the local code set differs from the code set specified to be used on the network), it determines which host code set converter to call to convert the data and then invokes that converter. The routine then returns the converted data, in idl_byte format. If the data is a varying, conformant, or conformant varying array, the routine also returns the length of the converted data, in units of idl_byte. Applications can specify local data types other than cs_byte and wchar_t (the local data types for which DCE RPC supplies stub code set conversion routines) with the cs_char ACF attribute. In this case, the application must also supply local_type_to_netcs() and local_type_from_netcs() stub conversion routines for this type. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: cs_byte_from_netcs wchar_t_from_netcs wchar_t_to_netcs 4 dce_cs_loc_to_rgy NAME dce_cs_loc_to_rgy - Maps a local name for a code set to a code set value in the code set registry Used by client and server applications. SYNOPSIS #include void dce_cs_loc_to_rgy( idl_char *local_code_set_name, unsigned32 *rgy_code_set_value, unsigned16 *rgy_char_sets_number, unsigned16 **rgy_char_sets_value, error_status_t *status ); PARAMETERS Input local_code_set_name A string that specifies the name that the local host's locale environment uses to refer to the code set. The string is a maximum of 32 bytes: 31 character data bytes plus a terminating NULL character. Output rgy_code_set_value The registered integer value that uniquely identifies the code set specified by local_code_set_name. rgy_char_sets_number The number of character sets that the specified code set encodes. Specifying NULL prevents this routine from returning this parameter. rgy_char_sets_value A pointer to an array of registered integer values that uniquely identify the character set(s) that the specified code set encodes. Specifying NULL prevents this routine from returning this parameter. The routine dynamically allocates this value. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: dce_cs_c_ok dce_cs_c_cannot_allocate_memory dce_cs_c_cannot_open_file dce_cs_c_cannot_read_file dce_cs_c_unknown dce_cs_c_not_found DESCRIPTION The dce_cs_loc_to_rgy() routine is a DCE function that maps operating system-specific names for character/code set encodings to their unique identifiers in the code set registry. The routine is currently used by the DCE RPC routines for character and code set interoperability, which permit DCE RPC clients and servers to transfer international character data in a heterogeneous character set and code sets environment. The dce_cs_loc_to_rgy() routine takes as input a string that holds the host-specific local name'' of a code set and returns the corresponding integer value that uniquely identifies that code set, as registered in the host's code set registry. If the integer value does not exist in the registry, the routine returns the status dce_cs_c_unknown. The routine also returns the number of character sets that the code set encodes and the registered integer values that uniquely identify those character sets. Specifying NULL in the rgy_char_sets_number and rgy_char_sets_value[] parameters prevents the routine from performing the additional search for these values. Applications that want only to obtain a code set value from the code set registry can specify NULL for these parameters in order to improve the routine's performance. If the value is returned from the routine, application developers should free the array after it is used, since the array is dynamically allocated. The DCE RPC code sets compatibility evaluation routines rpc_cs_eval_with_universal(), rpc_cs_eval_without_universal(), and rpc_cs_character_set_compat_check() use this routine to obtain registered integer values for a client and server's supported character sets in order to ensure that the server supports a character set that is compatible with the client. The DCE RPC stub support routines for code set conversion can use this routine to obtain the registered code set value that corresponds to the code set they are currently using; that is, the local code set specified in their host's locale environment. The stub routines for code set conversion then compare their local code set value to the code set value specified in the sending tag for the call to determine whether code set conversion is necessary. In general, programmers who are developing RPC applications that transfer international characters do not need to call this routine directly; the DCE RPC routines provided for code sets evaluation and the DCE RPC stub support routines for code set conversion call this routine on the client or server application's behalf. However, programmers who are developing their own stub support routines for code set conversion may want to include this routine in their conversion code to map their current locale information to a code set value in order to perform local-to-sending tag code set comparison. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Commands: csrc Functions: dce_cs_rgy_to_loc rpc_cs_char_set_compat_check rpc_cs_eval_with_universal rpc_cs_eval_without_universal rpc_rgy_get_code_sets 4 dce_cs_rgy_to_loc NAME dce_cs_rgy_to_loc - Maps a code set value in the code set registry to the local name for a code set Used by client and server applications. SYNOPSIS #include void dce_cs_rgy_to_loc( unsigned32 *rgy_code_set_value, idl_char **local_code_set_name, unsigned16 *rgy_char_sets_number, unsigned16 **rgy_char_sets_value, error_status_t *status ); PARAMETERS Input rgy_code_set_value The registered hexadecimal value that uniquely identifies the code set. Output local_code_set_name A string that specifies the name that the local host's locale environment uses to refer to the code set. The string is a maximum of 32 bytes: 31 character data bytes and a terminating NULL character. rgy_char_sets_number The number of character sets that the specified code set encodes. Specifying NULL in this parameter prevents the routine from returning this value. rgy_char_sets_value A pointer to an array of registered integer values that uniquely identify the character set(s) that the specified code set encodes. Specifying NULL in this parameter prevents the routine from returning this value. The routine dynamically allocates this value. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: dce_cs_c_ok dce_cs_c_cannot_allocate_memory dce_cs_c_cannot_open_file dce_cs_c_cannot_read_file dce_cs_c_unknown dce_cs_c_not_found DESCRIPTION The dce_cs_rgy_to_loc() routine is a DCE function that maps a unique identifier for a code set in the code set registry to the operating system-specific name for the code set, if it exists in the code set registry. The routine is currently used by the DCE RPC routines for character and code set interoperability, which permit DCE applications to transfer international characters in a heterogeneous character and code sets environment. The dce_cs_rgy_to_loc() routine takes as input a registered integer value of a code set and returns a string that holds the operating system-specific, or local name, of the code set. If the local code set name does not exist in the registry, the routine returns the status dce_cs_c_unknown and returns an undefined string. The routine also returns the number of character sets that the code set encodes and the registered integer values that uniquely identify those character sets. Specifying NULL in the rgy_char_sets_number and rgy_char_sets_value[] parameters prevents the routine from performing the additional search for these values. Applications that want only to obtain a local code set name from the code set registry can specify NULL for these parameters in order to improve the routine's performance. If the value is returned from the routine, application developers should free the rgy_char_sets_value array after it is used. In general, client and server applications that use the DCE RPC character and code set interoperablity features do not need to call this routine directly; the DCE RPC stub support routines provided for code set conversion call this routine on the client or server application's behalf to obtain the string name that matches the name of the host code set converter that they will call to perform the actual code set conversion. However, application programmers who are developing their own RPC stub support routines for code set conversion may want to include this routine in their conversion code to map code set values sent in code set tags into the local names for the code sets so that they can locate the correct operating system code set converter. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Commands: csrc. Functions: dce_cs_loc_to_rgy rpc_cs_char_set_compat_check rpc_cs_eval_with_universal rpc_cs_eval_without_universal rpc_rgy_get_code_sets 4 idl_es_decode_buffer NAME idl_es_decode_buffer - Returns a buffer decoding handle to the IDL encoding services SYNOPSIS void idl_es_decode_buffer( idl_byte *encoded_data_buffer, idl_ulong_int buffer_size, idl_es_handle_t *es_handle, error_status_t *status ); PARAMETERS Input encoded_data_buffer The address of the buffer that contains the data to be decoded. buffer_size The number of bytes of data in the buffer to be decoded. Output es_handle Returns the address of an IDL encoding services handle for use by a client or server decoding operation. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings include: rpc_s_ok Success. rpc_s_ss_bad_buffer Bad buffer operation. rpc_s_no_memory Insufficient memory available to complete operation. DESCRIPTION The IDL encoding services provide client and server RPC applications with a method for encoding data types in input parameters into a byte stream and decoding data types in output parameters from a byte stream without invoking the RPC runtime. Encoding and decoding operations are analogous to marshalling and unmarshalling, except that the data is stored locally, and is not transmitted over the network. Client and server applications can use the IDL encoding services to create persistent storage for their data. Encoding "flattens" complex data types into a byte stream for storage on disk, while decoding restores the flattened data to complex form. The idl_es_decode_buffer() routine belongs to a set of routines that return handles to the IDL encoding services for use by client and server encoding and decoding operations. The information in the handle controls the way in which the IDL encoding services manage memory when encoding or decoding data. The idl_es_decode_buffer() routine returns a buffer decoding handle, which directs the IDL encoding services to decode data from a single application-supplied buffer of encoded data. RETURNED VALUES None. RELATED INFORMATION Function: idl_es_decode_incremental 4 idl_es_decode_incremental NAME idl_es_decode_incremental - Returns an incremental decoding handle to the IDL encoding services Used by client and server applications. SYNOPSIS void idl_es_decode_incremental( idl_void_p_t state, idl_es_read_fn_t read_fn, idl_es_handle_t *es_handle, error_status_t *status ); PARAMETERS Input/Output state Specifies the address of an application-provided data structure that coordinates the actions of successive calls to the read_fn routine. The state data structure acts as a communications channel between the application and the read_fn routine. Input read_fn Specifies the address of a user-provided routine that generates a buffer of encoded data for decoding by the IDL encoding services. The IDL encoding services call the read_fn routine repeatedly until all of the data has been decoded. The following C definition for idl_es_read_fn_t illustrates the prototype for the read_fn routine: typedef void (*idl_es_read_fn_t) ( idl_void_p_t state, /* in/out */ idl_byte **buffer, /* in */ idl_ulong_int *size, /* in */ ); The idl_es_decode_incremental() routine passes the specified state parameter value as input to the read_fn routine. The state data structure is the communications path between the application and the read_fn routine. For example, the application can use the state parameter to pass in an open file pointer from which the read_fn routine is to read encoded data. The buffer parameter specifies the address of the data to be decoded; this address must be 8-byte aligned. The size parameter specifies the size of the buffer to be decoded, and must be a multiple of 8 bytes unless it represents the size of the last buffer to be decoded. The read_fn routine should return an exception on error. Output es_handle Returns the address of an IDL encoding services handle for use by a client or server decoding operation. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status code and its meaning is as follows: rpc_s_ok Success. rpc_s_no_memory Insufficient memory available to complete operation. DESCRIPTION The IDL encoding services provide client and server RPC applications with a method for encoding data types in input parameters into a byte stream and decoding data types in output parameters from a byte stream without invoking the RPC runtime. Encoding and decoding operations are analogous to marshalling and unmarshalling, except that the data is stored locally, and is not transmitted over the network. Client and server applications can use the IDL encoding services to create persistent storage for their data. Encoding "flattens" complex data types into a byte stream for storage on disk, while decoding restores the flattened data to complex form. The idl_es_decode_incremental() routine belongs to a set of routines that return handles to the IDL encoding services for use by client and server encoding and decoding operations. The information in the handle controls the way in which the IDL encoding services manage memory when encoding or decoding data. The idl_es_decode_incremental() routine returns an incremental decoding handle, which directs the IDL encoding services to decode data by calling the user-supplied read_fn routine, which generates a small buffer of encoded data for the IDL encoding services to decode. The routine passes the buffer address and size to the IDL encoding services, which then decode the buffer. The IDL encoding services call the read_fn routine repeatedly until there is no more data to decode. RETURN VALUES None. RELATED INFORMATION Functions: idl_es_encode_incremental idl_es_decode_buffer 4 idl_es_encode_dyn_buffer NAME idl_es_encode_dyn_buffer - Returns a dynamic buffer encoding handle to the IDL encoding services Used by client and server applications. SYNOPSIS void idl_es_encode_dyn_buffer( idl_byte **encoded_data_buffer, idl_ulong_int *buffer_size, idl_es_handle_t *es_handle, error_status_t *status ); PARAMETERS Input None. Output encoded_data_buffer The address to which the IDL encoding services will write the address of the buffer that contains the encoded data, when the encoding process is complete. When the application no longer needs the buffer, it should release the memory resource. See the OSF DCE Application Development Guide-Core Components for an explanation of how to manage memory when using the IDL encoding services. buffer_size The address to which the IDL encoding services will write the size of the buffer that contains the encoded data, when the encoding process is complete. es_handle Returns the address of an IDL encoding services handle for use by a client or server encoding operation. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_ss_bad_buffer Bad buffer operation. rpc_s_no_memory Insufficient memory available to complete operation. DESCRIPTION The IDL encoding services provide client and server RPC applications with a method for encoding data types in input parameters into a byte stream and decoding data types in output parameters from a byte stream without invoking the RPC runtime. Encoding and decoding operations are analogous to marshalling and unmarshalling, except that the data is stored locally, and is not transmitted over the network. Client and server applications can use the IDL encoding services to create persistent storage for their data. Encoding "flattens" complex data types into a byte stream for storage on disk, while decoding restores the flattened data to complex form. The idl_es_encode_dyn_buffer() routine belongs to a set of routines that return handles to the IDL encoding services for use by client and server encoding and decoding operations. The information in the handle controls the way in which the IDL encoding services manage memory when encoding or decoding data. The idl_es_encode_dyn_buffer() routine returns a dynamic buffer encoding handle, which directs the IDL encoding services to store the encoded data in a chain of small buffers, build an additional single buffer that contains the encoded data, and pass that buffer's address to the application. Dynamic buffering is the most expensive style of IDL encoding services buffering, since two copies of the encoded data exist (one in the chain of buffers, and one in the single buffer). RETURN VALUES None. RELATED INFORMATION Functions: idl_es_encode_fixed_buffer idl_es_encode_incremental 4 idl_es_encode_fixed_buffer NAME idl_es_encode_fixed_buffer - Returns a fixed buffer encoding handle to the IDL encoding services SYNOPSIS void idl_es_encode_fixed_buffer( idl_byte *data_buffer, idl_ulong_int data_buffer_size, idl_ulong_int *encoded_buffer_size, idl_es_handle_t *es_handle, error_status_t *status ); PARAMETERS Input data_buffer The address of the application-supplied buffer. This address must be 8-byte aligned. data_buffer_size The size of the application-supplied buffer. The size must be a multiple of 8 bytes. Output encoded_buffer_size Returns the address to which the IDL encoding services write the size of the encoded buffer when they have completed encoding the data. es_handle Returns the address of an IDL encoding services handle for use by a client or server encoding operation. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_bad_buffer Bad buffer operation. rpc_s_no_memory Insufficient memory available to complete operation. DESCRIPTION The IDL encoding services provide client and server RPC applications with a method for encoding data types in input parameters into a byte stream and decoding data types in output parameters from a byte stream without invoking the RPC runtime. Encoding and decoding operations are analogous to marshalling and unmarshalling, except that the data is stored locally, and is not transmitted over the network. Client and server applications can use the IDL encoding services to create persistent storage for their data. Encoding "flattens" complex data types into a byte stream for storage on disk, while decoding restores the flattened data to complex form. The idl_es_encode_fixed_buffer() routine belongs to a set of routines that return handles to the IDL encoding services for use by client and server encoding and decoding operations. The information in the handle controls the way in which the IDL encoding services manage memory when encoding or decoding data. The idl_es_encode_fixed_buffer() routine returns a fixed buffer encoding handle, which directs the IDL encoding services to encode data into a single buffer that the application has provided. The fixed buffer encoding style is useful for applications that need only one buffer for their encoding and decoding process. The buffer that the application allocates must be large enough to hold all of the encoded data, and must also allocate 56 bytes for each encoding operation that the application has defined (this space is used to hold per-operation header information.) RETURN VALUES None. RELATED INFORMATION Functions: idl_es_encode_dyn_buffer idl_es_encode_incremental 4 idl_es_encode_incremental NAME idl_es_encode_incremental - Returns an incremental encoding handle to the IDL encoding services Used by client and server applications. SYNOPSIS void idl_es_encode_incremental( idl_void_p_t state, idl_es_allocate_fn_t allocate_fn, idl_es_write_fn_t write_fn, idl_es_handle_t *es_handle, error_status_t *status ); PARAMETERS Input/Output state Specifies the address of an application-provided data structure that coordinates the actions of the allocate_fn and write_fn routines. The state data structure acts as a communications channel between the application and the allocate_fn and write_fn routines. Input allocate_fn Specifies the address of a user-provided routine that allocates an empty buffer. The encoding stub uses the allocated buffer to store encoded data. The following C definition for idl_es_allocate_fn_t illustrates the prototype for the buffer allocation routine: typedef void (*idl_es_allocate_fn_t) ( idl_void_p_t state, /* in/out */ idl_byte **buffer, /* out */ idl_ulong_int *size, /* in/out */ ); The idl_es_encode_incremental() routine passes the specified state parameter value as input to the allocate_fn buffer allocation routine. When the IDL encoding services call the allocate_fn routine, the value at the address indicated by size represents the buffer size that the IDL encoding services have requested the routine to allocate. When the allocate_fn buffer allocation routine allocates the buffer, it writes the actual size of the allocated buffer to this parameter; the value must be a multiple of eight bytes. The buffer parameter specifies the address of the allocated buffer; this address must be 8-byte aligned. The allocate_fn routine should return an exception on error. write_fn Specifies the address of a user-provided routine that writes the contents of a buffer that contains data that has been encoded by the IDL encoding services. The IDL encoding services will call this routine when the buffer allocated by allocate_fn is full, or when all of the application's encoding operation parameters have been encoded. The following C definition for idl_es_write_fn_t illustrates the prototype for the write_fn routine: typedef void (*idl_es_write_fn_t) ( idl_void_p_t state, /* in/out */ idl_byte *buffer, /* in */ idl_ulong_int size, /* in */ ); The idl_es_encode_incremental() routine passes the specified state parameter value as input to the write_fn routine. The buffer parameter value is the address of the data that the IDL encoding services have encoded. The size parameter value is the size, in bytes, of the encoded data. The write_fn routine should return an exception on error. Output es_handle Returns the address of an IDL encoding services handle for use by a client or server encoding operation. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_no_memory Insufficient memory available to complete operation. DESCRIPTION The IDL encoding services provide client and server RPC applications with a method for encoding data types in input parameters into a byte stream and decoding data types in output parameters from a byte stream without invoking the RPC runtime. Encoding and decoding operations are analogous to marshalling and unmarshalling, except that the data is stored locally, and is not transmitted over the network. Client and server applications can use the IDL encoding services to create persistent storage for their data. Encoding "flattens" complex data types into a byte stream for storage on disk, while decoding restores the flattened data to complex form. The idl_es_encode_incremental() routine belongs to a set of routines that return handles to the IDL encoding services for use by client and server encoding and decoding operations. The information in the handle controls the way in which the IDL encoding services manage memory when encoding or decoding data. The idl_es_encode_incremental() routine returns an incremental encoding handle, which directs the IDL encoding services to encode data into a chain of small buffers that the user-provided allocate_fn routine manages. The user-provided write_fn routine writes the encoded data in these buffers back for access by the application. The state data structure is the communications path between the application and the allocate_fn and write_fn routines. For example, the application can build a cache of pre-allocated memory to store encoded data, and store pointers to that pre-allocated memory in the state data structure. When invoked by the IDL encoding services to allocate a buffer, the allocate_fn routine can search the state data structure for a free memory location to use. RETURN VALUES None. RELATED INFORMATION Functions: idl_es_decode_incremental idl_es_encode_fixed_buffer idl_es_encode_dyn_buffer 4 idl_es_handle_free NAME idl_es_handle_free - Frees an IDL encoding services handle SYNOPSIS void idl_es_handle_free( idl_es_handle_t *es_handle, error_status_t *status ); PARAMETERS Input/Output es_handle The address of the handle whose resources are to be freed. The handle is made NULL by this operation. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status code and its meaning is as follows: rpc_s_ok Success. DESCRIPTION The idl_es_handle_free routine frees an IDL encoding services handle that has been allocated by one of the IDL encoding services handle- returning routines. RETURNED VALUES None. RELATED INFORMATION Functions: idl_es_decode_buffer idl_es_decode_incremental idl_es_encode_dyn_buffer idl_es_encode_fixed_buffer idl_es_encode_incremental 4 idl_es_inq_encoding_id NAME idl_es_inq_encoding_id - Identifies an operation within an interface that has been called to encode data using the IDL encoding services SYNOPSIS void idl_es_inq_encoding_id( idl_es_handle_t es_handle, rpc_if_id_t *if_id, idl_ulong_int *op_num, error_status_t *status ); PARAMETERS Input es_handle A encoding services handle returned by one of the IDL encoding services handle-returning routines. Output if_id Returns the interface UUID and version number assigned to the interface that defines the operation that encoded the data. This information is stored in the IDL encoding services handle that is associated with the encoded data. op_num Returns the operation number assigned to the operation that encoded the data. Operations are numbered in the order in which they appear in the interface definition, starting with zero (0). The operation number for the operation that encoded the data is stored in the IDL encoding services handle that is associated with the encoded data. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_unknown_if Interface identifier and operation number unavailable. DESCRIPTION The IDL encoding services provide client and server RPC applications with a method for encoding data types in input parameters into a byte stream and decoding data types in output parameters from a byte stream without invoking the RPC runtime. Encoding and decoding operations are analogous to marshalling and unmarshalling, except that the data is stored locally, and is not transmitted over the network. Client and server applications can use the IDL encoding services to create persistent storage for their data. Encoding "flattens" complex data types into a byte stream for storage on disk, while decoding restores the flattened data to complex form. The idl_es_inq_encoding_id() routine returns the identity of an operation within an application that has been invoked to encode data using the IDL encoding services. Applications can use this routine to determine the identity of an encoding operation, for example, before calling their decoding operations. RETURN VALUES None. RELATED INFORMATION Functions: idl_es_decode_buffer idl_es_decode_incremental idl_es_encode_dyn_buffer idl_es_encode_fixed_buffer idl_es_encode_incremental 4 rpc_binding_copy NAME rpc_binding_copy - Returns a copy of a binding handle Used by client or server applications. SYNOPSIS #include void rpc_binding_copy( rpc_binding_handle_t source_binding, rpc_binding_handle_t *destination_binding, unsigned32 *status ); PARAMETERS Input source_binding Specifies the server binding handle whose referenced binding information is copied. Output destination_binding Returns the server binding handle that refers to the copied binding information. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_invalid_binding Invalid binding handle. rpc_s_wrong_kind_of_binding Wrong kind of binding for operation. DESCRIPTION The rpc_binding_copy() routine copies the server binding information referenced by the binding handle specified in the source_binding parameter. This routine returns a new server binding handle for the copied binding information. The new server binding handle is returned in the destination_binding parameter. Use the rpc_binding_copy() routine if you want a change (made to binding information by one thread) not to affect the binding infor- mation used by other threads. The explanation of binding handles in the rpc_intro reference page has more detail about this use of routine rpc_binding_copy(). After calling this routine, operations performed on the source_binding binding handle do not affect the binding information referenced by the destination_binding binding handle. Similarly, operations performed on the destination_binding binding handle do not affect the binding information referenced by the source_binding binding handle. If you want the changes made to binding information by one thread to affect the binding information used by other threads, your program must share a single binding handle across the threads. In this case the application controls binding handle concurrency. When an application is finished using the binding handle specified by the destination_binding parameter, the application calls the rpc_binding_free() routine to release the memory used by the destination_binding binding handle and its referenced binding information. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_free 4 rpc_binding_free NAME rpc_binding_free - Releases binding handle resources Used by client or server applications. SYNOPSIS #include void rpc_binding_free( rpc_binding_handle_t *binding, unsigned32 *status ); PARAMETERS Input/Output binding Specifies the server binding handle to free. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_invalid_binding Invalid binding handle. rpc_s_wrong_kind_of_binding Wrong kind of binding for operation. DESCRIPTION The rpc_binding_free() routine frees the memory used by a server binding handle and its referenced binding information. Use this routine when your application is finished using a server binding handle that was dynamically created during program execution. If the free-binding operation succeeds, the binding parameter returns the value NULL. An application can dynamically create binding handles by calling any of the following routines: + rpc_binding_copy() + rpc_binding_from_string_binding() + rpc_ns_binding_import_next() + rpc_ns_binding_select() + rpc_server_inq_bindings() RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_copy rpc_binding_from_string_binding rpc_binding_vector_free rpc_ns_binding_import_next rpc_ns_binding_lookup_next rpc_ns_binding_select rpc_server_inq_bindings 4 rpc_binding_from_string_binding NAME rpc_binding_from_string_binding - Returns a binding handle from a string representation Used by client or management applications. SYNOPSIS #include void rpc_binding_from_string_binding( unsigned_char_t *string_binding, rpc_binding_handle_t *binding, unsigned32 *status ); PARAMETERS Input string_binding Specifies a string representation of a binding handle. Output binding Returns the server binding handle. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_invalid_arg Invalid argument. rpc_s_invalid_endpoint_format Invalid endpoint format. rpc_s_invalid_rpc_protseq Invalid protocol sequence. rpc_s_invalid_string_binding Invalid string binding. rpc_s_protseq_not_supported Protocol sequence not supported on this host. uuid_s_bad_version Bad UUID version. uuid_s_invalid_string_uuid Invalid format for a string UUID. DESCRIPTION The rpc_binding_from_string_binding() routine creates a server binding handle from a string representation of a binding handle. The string_binding parameter does not need to contain an object UUID. In this case, the returned binding contains a nil UUID. If the provided string_binding parameter does not contain an endpoint field, the returned binding parameter is a partially bound server binding handle. If the provided string_binding parameter does contain an endpoint field, the returned binding parameter is a fully bound server binding handle with a well-known endpoint. If the provided string_binding parameter does not contain a host address field, the returned binding parameter refers to the local host. To create a string binding, call the rpc_string_binding_compose() routine or call the rpc_binding_to_string_binding() routine or provide a character string constant. When an application finishes using the binding parameter, the application calls the rpc_binding_free() routine to release the memory used by the binding handle. The rpc_intro reference page contains an explanation of partially and fully bound binding handles. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_copy rpc_binding_free rpc_binding_to_string_binding rpc_string_binding_compose 4 rpc_binding_inq_auth_client NAME rpc_binding_inq_auth_client - Returns authentication and authorization information from the binding handle for an authenticated client. This call is provided only for compatibility with pre-1.1 DCE applications. DCE Release 1.1 and later applications should use the rpc_binding_inq_auth_caller() call. Used by server applications. SYNOPSIS #include #include void rpc_binding_inq_auth_client( rpc_binding_handle_t binding, rpc_authz_handle_t *privs, unsigned_char_t **server_princ_name, unsigned32 *protect_level, unsigned32 *authn_svc, unsigned32 *authz_svc, unsigned32 *status ); PARAMETERS Input binding Specifies the client binding handle from which to return the authentication and authorization information. Output privs Returns a handle to the authorization information for the client that made the remote procedure call on binding. The server must cast this handle to the data type specified by authz_svc. The following table shows how to cast the return value. Casts for Authorization Information ____________________________________________________________________ For authz_svc value: privs contains this data: Use this cast: ____________________________________________________________________ rpc_c_authz_none A NULL value. None rpc_c_authz_name The calling client's (unsigned_char_t *) principal name. rpc_c_authz_dce The calling client's (sec_id_pac_t *) privilege attribute certificate. Note that rpc_c_authz_none is valid only if the authn_svc parameter is rpc_c_authn_none. The data referenced by this parameter is read-only and should not be modified by the server. If the server wants to preserve any of the returned data, it must copy the data into server-allocated memory. Specifying NULL prevents the routine from returning this parameter. server_princ_name Returns a pointer to the server principal name specified by the client that made the remote procedure call on binding. The content of the returned name and its syntax is defined by the authentication service in use. Specifying NULL prevents the routine from returning this parameter. In this case, the caller does not have to call the rpc_string_free() routine. protect_level Returns the protection level requested by the client that made the remote procedure call on binding. The protection level determines the degree to which authenticated communications between the client and the server are protected. Specifying NULL prevents the routine from returning this parameter. The possible protection levels are as follows: rpc_c_protect_level_default Uses the default protection level for the specified authentication service. rpc_c_protect_level_none Performs no protection. rpc_c_protect_level_connect Performs protection only when the client establishes a relationship with the server. rpc_c_protect_level_call Performs protection only at the beginning of each remote procedure call when the server receives the request. rpc_c_protect_level_pkt Ensures that all data received is from the expected client. rpc_c_protect_level_pkt_integ Ensures and verifies that none of the data transferred between client and server has been modified. rpc_c_protect_level_pkt_privacy Performs protection as specified by all of the previous levels and also encrypt each remote procedure call argument value. authn_svc Returns the authentication service requested by the client that made the remote procedure call on binding. Specifying NULL prevents the routine from returning this parameter. The possible authentication services are as follows: rpc_c_authn_none No authentication. rpc_c_authn_dce_secret DCE shared-secret key authentication. rpc_c_authn_dce_public DCE public key authentication (reserved for future use). rpc_c_authn_default DCE default authentication service. authz_svc Returns the authorization service requested by the client that made the remote procedure call on binding. Specifying NULL prevents the routine from returning this parameter. The possible authorization services are as follows: rpc_c_authz_none Server performs no authorization. This is valid only if the authn_svc parameter is rpc_c_authn_none. rpc_c_authz_name Server performs authorization based on the client principal name. rpc_c_authz_dce Server performs authorization using the client's DCE Privilege Attribute Certificate (PAC) sent to the server with each remote procedure call made with binding. Generally, access is checked against DCE Access Control Lists (ACLs). status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_invalid_binding Invalid binding handle. rpc_s_wrong_kind_of_binding Wrong kind of binding for operation. rpc_s_binding_has_no_auth Binding has no authentication information. DESCRIPTION The rpc_binding_inq_auth_client() routine returns authentication and authorization information associated with the client identified by binding. The calling server manager routine can use the returned data for authorization purposes. This call is provided only for compatibility with pre-1.1 DCE applications. DCE Release 1.1 and later applications should use the rpc_binding_inq_auth_caller() call. The RPC runtime allocates memory for the returned server_princ_name parameter. The server is responsible for calling the rpc_string_free() routine for the returned parameter string. For applications in which the client side uses the IDL auto_handle or implicit_handle attribute, the server side needs to be built with the IDL explicit_handle attribute specified in the Attribute Configuration File (ACF). Using explicit_handle provides binding as the first parameter to each server manager routine. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_inq_auth_info rpc_binding_set_auth_info rpc_string_free 4 rpc_binding_inq_auth_info NAME rpc_binding_inq_auth_info - Returns authentication and authorization information from a server binding handle Used by client applications. SYNOPSIS #include #include void rpc_binding_inq_auth_info( rpc_binding_handle_t binding, unsigned_char_t **server_princ_name, unsigned32 *protect_level, unsigned32 *authn_svc, rpc_auth_identity_handle_t *auth_identity, unsigned32 *authz_svc, unsigned32 *status ); PARAMETERS Input binding Specifies the server binding handle from which to return the authentication and authorization information. Output server_princ_name Returns a pointer to the expected principal name of the server referenced by binding. The content of the returned name and its syntax is defined by the authentication service in use. Specifying NULL prevents the routine from returning this parameter. In this case, the caller does not have to call the rpc_string_free() routine. protect_level Returns the protection level used for remote procedure calls made with binding. The protection level determines the degree to which authenticated communications between the client and the server are protected. Note that the returned level may be different from the level specified for protect_level on the call to rpc_binding_set_auth_info(). If the RPC runtime or the RPC protocol in the bound protocol sequence does not support a specified level, the level is automatically upgraded to the next higher supported level. Specifying NULL prevents the routine from returning this parameter. The possible protection levels are as follows: rpc_c_protect_level_default Uses the default protection level for the specified authentication service. rpc_c_protect_level_none Performs no protection. rpc_c_protect_level_connect Performs protection only when the client establishes a relationship with the server. rpc_c_protect_level_call Performs protection only at the beginning of each remote procedure call when the server receives the request. rpc_c_protect_level_pkt Ensures that all data received is from the expected client. rpc_c_protect_level_pkt_integ Ensures and verifies that none of the data transferred between client and server has been modified. rpc_c_protect_level_pkt_privacy Performs protection as specified by all of the previous levels and also encrypt each remote procedure call parameter value. authn_svc Returns the authentication service used for remote procedure calls made with binding. Specifying NULL prevents the routine from returning this argument. The possible authentication services are as follows: rpc_c_authn_none No authentication. rpc_c_authn_dce_secret DCE shared-secret key authentication. rpc_c_authn_dce_public DCE public key authentication (reserved for future use). rpc_c_authn_default DCE default authentication service. auth_identity Returns a handle for the data structure that contains the client's authentication and authorization credentials. This parameter must be cast as appropriate for the authentication and authorization services established via rpc_binding_set_auth_info(). When using the rpc_c_authn_dce_secret authentication service and any authorization service, this value must be a sec_login_handle_t obtained from one of the following routines: + sec_login_setup_identity() + sec_login_get_current_context() + sec_login_newgroups() These routines are described in Chapter 5 of this manual. Specifying NULL prevents the routine from returning this parameter. authz_svc Returns the authorization service used for remote procedure calls made with binding. Specifying NULL prevents the routine from returning this parameter. The possible authorization services are as follows: rpc_c_authz_none Server performs no authorization. This is valid only if the authn_svc parameter is rpc_c_authn_none. rpc_c_authz_name Server performs authorization based on the client principal name. rpc_c_authz_dce Server performs authorization using the client's DCE Privilege Attribute Certificate (PAC) sent to the server with each remote procedure call made with binding. Generally, access is checked against DCE Access Control Lists (ACLs). status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_invalid_binding Invalid binding handle. rpc_s_wrong_kind_of_binding Wrong kind of binding for operation. rpc_s_binding_has_no_auth Binding has no authentication information. DESCRIPTION The rpc_binding_inq_auth_info() routine returns authentication and authorization information associated with the specified server binding handle. The calling client associates the authentication and authorization data with the server binding handle by a prior call to the rpc_binding_set_auth_info() routine. The RPC runtime allocates memory for the returned server_princ_name parameter. The caller is responsible for calling the rpc_string_free() routine for the returned parameter string. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_set_auth_info rpc_string_free 4 rpc_binding_inq_object NAME rpc_binding_inq_object - Returns the object UUID from a binding handle Used by client or server applications. SYNOPSIS #include void rpc_binding_inq_object( rpc_binding_handle_t binding, uuid_t *object_uuid, unsigned32 *status ); PARAMETERS Input binding Specifies a client or server binding handle. Output object_uuid Returns the object UUID found in the binding parameter. The object UUID is a unique identifier for an object for which a remote procedure call can be made. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_invalid_binding Invalid binding handle. DESCRIPTION The rpc_binding_inq_object() routine obtains the object UUID associated with a client or server binding handle. If no object UUID has been associated with the binding handle, this routine returns a nil UUID. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_set_object 4 rpc_binding_reset NAME rpc_binding_reset - Resets a server binding handle Used by client or management applications. SYNOPSIS #include void rpc_binding_reset( rpc_binding_handle_t binding, unsigned32 *status ); PARAMETERS Input binding Specifies the server binding handle to reset. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_invalid_binding Invalid binding handle. rpc_s_wrong_kind_of_binding Wrong kind of binding for operation. DESCRIPTION The rpc_binding_reset() routine disassociates a server instance from the server binding handle specified in the binding parameter. This routine removes the endpoint portion of the server address in the binding handle as well as any other server instance information in the binding handle. The host portion of the server address remains unchanged. The result is a partially bound server binding handle. This binding handle can rebind to another server instance on the previous host when it is later used to make a remote procedure call. The rpc_intro reference page contains an explanation of partially and fully bound binding handles. This routine does not affect any authentication information for the binding parameter. Suppose that a client can be serviced by any compatible server instance on the host specified in the binding handle. Then, the client can call the rpc_binding_reset() routine before making a remote procedure call using the binding handle specified in binding. When the client makes the next remote procedure call using the reset server binding handle in binding, the client's RPC runtime uses a well-known endpoint from the client's interface specification, if any. Otherwise, the client's RPC runtime automatically communicates with the DCE Host Daemon (dced) on the specified remote host, to obtain the endpoint of a compatible server from the local endpoint map. If a compatible server is located, the RPC runtime updates binding with a new endpoint. However, if a compatible server is not located, the client's remote procedure call fails. If the failed call uses a connection protocol (ncacn), it receives the rpc_s_endpoint_not_found status code. If the failed call uses a datagram protocol (ncadg), it receives the rpc_s_comm_failure status code. If a server application wants to be available to clients making a remote procedure call on a reset binding handle, it registers all binding handles by calling rpc_ep_register() or rpc_ep_register_no_replace(). If, however, the IDL-generated file contains endpoint address information, then the application does not have to call either of these two routines. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ep_register rpc_ep_register_no_replace 4 rpc_binding_server_from_client NAME rpc_binding_server_from_client - Converts a client binding handle to a server binding handle Used by server applications. SYNOPSIS #include void rpc_binding_server_from_client( rpc_binding_handle_t client_binding, rpc_binding_handle_t *server_binding, unsigned32 *status ); PARAMETERS Input client_binding Specifies the client binding handle to convert to a server binding handle. Output server_binding Returns a server binding handle. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_cant_getpeername Cannot get peer name. rpc_s_connection_closed Connection closed. rpc_s_invalid_binding Invalid binding handle. rpc_s_wrong_kind_of_binding Wrong kind of binding. DESCRIPTION When a remote procedure call arrives at a server, the RPC runtime creates a client binding handle to refer to information about the calling client (client binding information). The RPC runtime passes the client binding handle to the called remote procedure as the first input argument (which uses the handle_t type). The rpc_binding_server_from_client() routine converts client binding information into server binding information corresponding to the client's system. When calling this routine, the called remote procedure specifies the client binding handle, and the routine returns a partially bound server binding handle (that is, the newly constructed server binding information contains a network address for the client's system, but lacks an endpoint). The server binding information also lacks authentication information, but the called procedure can add it by calling rpc_binding_set_auth_info(). The object UUID from the client binding information remains. The rpc_binding_server_from_client() routine is relevant when a called remote procedure (the first remote procedure) needs to make its own remote procedure call (a nested procedure call) to a second remote procedure offered by a server on the system of the client that called the first remote procedure (that is, the original client). The partially bound server binding handle returned by the rpc_binding_server_from_client() routine ensures that a nested call requests the second remote procedure on the original client's system. In a multithreaded RPC application, the second remote procedure can belong to a server that shares the original client's address space (that is, the server and client can operate jointly as a server/client instance). If the original client belongs to a server/client instance and the application requires the nested call to execute in that instance, the application must guarantee that the nested remote procedure call uses one of the instances' endpoints. An application can provide this guarantee by meeting any of the following conditions: + The interface possesses its own well-known endpoints, and the server elects to use these interface-specific endpoints (by calling rpc_server_use_protseq_if() or rpc_server_use_all_protseqs_if()). + The server uses server-specific endpoints, and the interface is offered by only one server/client instance per system. To use server-specific endpoints, a server either requests dynamic endpoints (by calling rpc_server_use_protseq() or rpc_server_use_all_protseqs()) or specifies its own well-known endpoints (by calling rpc_server_use_protseq_ep()). The server must also register its server-specific endpoints in the local endpoint map (by calling rpc_ep_register()). + The original client sets an object UUID into the server binding information of the first call (by calling rpc_binding_set_object()); the object UUID identifies the server/client instance. The client can obtain the object UUID from the list of object UUIDs used to register the endpoints of the server/client instance. The client must select an object UUID that belongs exclusively to its instance. Server binding information containing an object UUID impacts the selection of a manager for a remote procedure call; see the OSF DCE Application Development Guide for a description of manager selection. The object UUID can either identify a particular resource offered by the companion server or, used as an instance UUID, the object UUID can identify the original client's server/client instance. The object UUID is passed in the first remote procedure call as part of the client binding information and is retained in the server binding information. This server binding information is newly constructed by the rpc_binding_server_from_client() routine. When the second remote procedure call arrives at the original client's system, the DCE Host daemon uses the object UUID to look for associated endpoints in the local endpoint map. To ensure that the object UUID is associated with the endpoints of the original server/client instance, the server must complete the following steps: 1. Obtain the UUID (for example, by calling uuid_create()). 2. Specify the UUID as part of registering endpoints for the interface of the second remote procedure (by calling rpc_ep_register() or rpc_ep_register_no_replace()). If the second remote procedure call will be routed to a manager of a non-nil type, then the server must also do the following: 1. Specify the type for the manager that implements that interface (by calling rpc_server_register_if()). 2. Set the object UUID to the same type as the manager (by calling rpc_object_set_type()). + The first remote procedure call contains a distinct call argument used by the original client to pass server information that identifies its server/client instance. The first remote procedure call uses this information to route the second remote procedure call to the original server/client instance. For example, server information can be as follows: - A fully bound string binding that identifies the client's server/client instance. If the first remote procedure receives this string binding, calling the rpc_binding_server_from_client routine is unnecessary. Instead, the first remote procedure requests a server binding handle for the string binding (by calling rpc_binding_from_string_binding()). - An object UUID that is associated in the endpoint map with one or more endpoints of the original server/client instance. The client can obtain the object UUID from the list of object UUIDs used to register the endpoints of the server/client instance. The client must select an object UUID that belongs exclusively to its instance, and pass that UUID as a call argument. After calling the rpc_binding_server_from_client() routine, add the object UUID from the call argument to the newly constructed server binding information (by calling rpc_binding_set_object()). RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_free rpc_binding_set_object rpc_ep_register rpc_ep_register_no_replace Books: DCE OSF Application Development Guide. 4 rpc_binding_set_auth_info NAME rpc_binding_set_auth_info - Sets authentication and authorization information for a server binding handle Used by client applications. SYNOPSIS #include #include void rpc_binding_set_auth_info( rpc_binding_handle_t binding, unsigned_char_t *server_princ_name, unsigned32 protect_level, unsigned32 authn_svc, rpc_auth_identity_handle_t auth_identity, unsigned32 authz_svc, unsigned32 *status ); PARAMETERS Input binding Specifies the server binding handle for which to set the authentication and authorization information. server_princ_name Specifies the principal name of the server referenced by binding. The content of the name and its syntax is defined by the authentication service in use. A client that does not know the server principal name can call the rpc_mgmt_inq_server_princ_name() routine to obtain the principal name of a server that is registered for the required authentication service. Using a principal name obtained in this way means that the client is interested in one-way authentication. In other words, it means that the client does not care which server principal received the remote procedure call request. The server, though, still verifies that the client is who the client claims to be. protect_level Specifies the protection level for remote procedure calls made using binding. The protection level determines the degree to which authenticated communications between the client and the server are protected by the authentication service specified by authn_svc. If the RPC runtime or the RPC protocol in the bound protocol sequence does not support a specified level, the level is automatically upgraded to the next higher supported level. The possible protection levels are as follows: rpc_c_protect_level_default Uses the default protection level for the specified authentication service. The default protection level for the DCE shared-secret key authentication service is rpc_c_protect_level_pkt_integ. rpc_c_protect_level_none Performs no authentication: tickets are not exchanged, session keys are not established, client PACs or names are not certified, and transmissions are in the clear. Note that although uncertified PACs should not be trusted, they may be useful for debugging, tracing, and measurement purposes. rpc_c_protect_level_connect Performs protection only when the client establishes a relationship with the server. rpc_c_protect_level_call Performs protection only at the beginning of each remote procedure call when the server receives the request. This level does not apply to remote procedure calls made over a connection-based protocol sequence (that is, ncacn_ip_tcp). If this level is specified and the binding handle uses a connection-based protocol sequence, the routine uses the rpc_c_protect_level_pkt level instead. rpc_c_protect_level_pkt Ensures that all data received is from the expected client. rpc_c_protect_level_pkt_integ Ensures and verifies that none of the data transferred between client and server has been modified. This is the highest protection level that is guaranteed to be present in the RPC runtime. rpc_c_protect_level_pkt_privacy Performs protection as specified by all of the previous levels and also encrypt each remote procedure call argument value. This is the highest protection level, but it may not be available in the RPC runtime. authn_svc Specifies the authentication service to use. The exact level of protection provided by the authentication service is specified by the protect_level parameter. The supported authentication services are as follows: rpc_c_authn_none No authentication: no tickets are exchanged, no session keys established, client PACs or names are not transmitted, and transmissions are in the clear. Specify rpc_c_authn_none to turn authentication off for remote procedure calls made using binding. rpc_c_authn_dce_secret DCE shared-secret key authentication. rpc_c_authn_default DCE default authentication service. The current default authentication service is DCE shared-secret key; therefore, specifying rpc_c_authn_default is equivalent to specifying rpc_c_authn_dce_secret. rpc_c_authn_dce_public DCE public key authentication (reserved for future use). rpc_c_authn_winnt Authentication via Microsoft NT Lan Manager (only available on Windows NT and OpenVMS). This allows OpenVMS applications to authenticate with a Windows NT domain security server. auth_identity Specifies a handle for the data structure that contains the client's authentication and authorization credentials appropriate for the selected authentication and authorization services. When using the rpc_c_authn_dce_secret authentication service and any authorization service, this value must be a sec_login_handle_t obtained from one of the following routines: + sec_login_setup_identity() + sec_login_get_current_context() + sec_login_newgroups() + rpc_winnt_set_auth_identity Specify NULL to use the default security login context for the current address space. authz_svc Specifies the authorization service implemented by the server for the interface of interest. The validity and trustworthiness of authorization data, like any application data, is dependent on the authentication service and protection level specified. The supported authorization services are as follows: rpc_c_authz_none Server performs no authorization. This is valid only if the authn_svc parameter is rpc_c_authn_none, specifying that no authentication is being performed. rpc_c_authz_name Server performs authorization based on the client principal name. This value cannot be used if authn_svc is rpc_c_authn_none. rpc_c_authz_dce Server performs authorization using the client's DCE Privilege Attribute Certificate (PAC) sent to the server with each remote procedure call made with binding. Generally, access is checked against DCE Access Control Lists (ACLs). This value cannot be used if authn_svc is rpc_c_authn_none. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_invalid_binding Invalid binding handle. rpc_s_wrong_kind_of_binding Wrong kind of binding for operation. rpc_s_unknown_authn_service Unknown authentication service. rpc_s_authn_authz_mismatch Requested authorization service is not supported by the requested authentication service. rpc_s_unsupported_protect_level Requested protection level is not supported. DESCRIPTION The rpc_binding_set_auth_info() routine sets up the specified server binding handle so that it can be used to make authenticated remote procedure calls that include authorization information. Unless a client calls rpc_binding_set_auth_info() with the parameters to set establish authentication and authorization methods, all remote procedure calls made on the binding binding handle are unauthenti- cated.Some authentication services (authn_svc) may need to communicate with the Security service to perform this operation. Otherwise, they may receive the rpc_s_comm_failure status. The authn_svc parameter specifies the authentication service to use. Since currently, there is only one available authentication service (DCE shared-secret key), the parameter currently functions to specify whether or not rpc calls will be authenticated and client PACs certified. If authentication is chosen, the protect_level parameter can specify a variety of protection levels, ranging from no authentication to the highest level of authentication and encryption. If the protect_level parameter is set to rpc_c_protect_level_none, no authentication is performed, regardless of the authentication service chosen. The authz_svc parameter specifies the authorization service to use. If no authentication has been chosen (authn_svc of rpc_c_authn_none), then no authorization (authz_svc of rpc_c_authz_none) must be chosen as well. If authentication will be performed, you have two choices for authorization: name-based authorization and DCE authorization. The use of name based_authorization, which provides a server with a client's principal name, is not recommended. DCE authorization uses PACs, a trusted mechanism for conveying client authorization data to authenticated servers. PACs are designed to be used with the DCE ACL facility. Whether the call actually wakes up in the server manager code or is rejected by the runtime depends on following conditions: + If the client specified no authentication, then none is attempted by the RPC runtime.The call wakes up in the manager code whether the server specified authentication or not. This permits both authenticated and unauthenticated clients to call authenticated servers. When the manager receives an unauthenticated call, it needs to make a decision about how to proceed. + If the client specified DCE secret key authentication and the server specified no authentication, then the runtime will fail the call, and it will never reach the manager routine. + If both client and server specified DCE secret key authentication, then authentication will be carried out by the RPC runtime transparently. Whether the call reaches the server manager code or is rejected by the runtime depends on whether the authentication succeeded. Although the RPC runtime is responsible any authentication that is carried out, the fact that the runtime will always permit unauthenticated clients to reach the manager code means that a manager access function typically does need to make an authentication check. When the manager access routine calls rpc_binding_inq_auth_client() it needs to check for a status of rpc_s_binding_has_no_auth. In this case, the client has specified no authentication and the manager access function needs to make an access decision based on this fact. Note that in such a case, no meaningful authentication or authorization information is returned from rpc_binding_inq_auth_client(). RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_inq_auth_client rpc_binding_inq_auth_info rpc_mgmt_inq_dflt_protect_level rpc_mgmt_inq_server_princ_name sec_login_get_current_context sec_login_newgroups sec_login_setup_identity 4 rpc_binding_set_object NAME rpc_binding_set_object - Sets the object UUID value into a server binding handle. Used by client applications. SYNOPSIS #include void rpc_binding_set_object( rpc_binding_handle_t binding, uuid_t *object_uuid, unsigned32 *status ); PARAMETERS Input binding Specifies the server binding into which parameter object_uuid is set. Supply NULL to specify a nil UUID for this parameter. object_uuid Specifies the UUID of the object serviced by the server specified in the binding parameter. The object UUID is a unique identifier for an object for which a remote procedure call can be made. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_invalid_binding Invalid binding handle. rpc_s_wrong_kind_of_binding Wrong kind of binding for operation. DESCRIPTION The rpc_binding_set_object() routine associates an object UUID with a server binding handle. This operation replaces the previously associated object UUID with the UUID in the object_uuid parameter. To set the object UUID to the nil UUID, specify NULL or the nil UUID for the object_uuid parameter. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_from_string_binding rpc_binding_inq_object 4 rpc_binding_to_string_binding NAME rpc_binding_to_string_binding - Returns a string representation of a binding handle Used by client, server, or management applications. SYNOPSIS #include void rpc_binding_to_string_binding( rpc_binding_handle_t binding, unsigned_char_t **string_binding, unsigned32 *status ); PARAMETERS Input binding Specifies a client or server binding handle to convert to a string representation of a binding handle. Output string_binding Returns a pointer to the string representation of the binding handle specified in the binding parameter. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_cant_getpeername Cannot get peer name. rpc_s_connection_closed Connection closed. rpc_s_invalid_binding Invalid binding handle. DESCRIPTION The rpc_binding_to_string_binding() routine converts a client or server binding handle to its string representation. The RPC runtime allocates memory for the string returned in the string_binding parameter. The application calls the rpc_string_free() routine to deallocate that memory. If the binding handle in the binding parameter contains a nil object UUID, the object UUID field is not included in the returned string. To parse the returned string_binding parameter, call rpc_string_binding_parse(). RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_from_string_binding rpc_string_binding_parse rpc_string_free 4 rpc_binding_vector_free NAME rpc_binding_vector_free - Frees the memory used to store a vector and binding handles Used by client or server applications. SYNOPSIS #include void rpc_binding_vector_free( rpc_binding_vector_t **binding_vector, unsigned32 *status ); PARAMETERS Input/Output binding_vector Specifies the address of a pointer to a vector of server binding handles. On return the pointer is set to NULL. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_invalid_arg Invalid argument. rpc_s_invalid_binding Invalid binding handle. rpc_s_wrong_kind_of_binding Wrong kind of binding for operation. DESCRIPTION The rpc_binding_vector_free() routine frees the memory used to store a vector of server binding handles. The freed memory includes both the binding handles and the vector itself. A server obtains a vector of binding handles by calling rpc_server_inq_bindings(). A client obtains a vector of binding handles by calling rpc_ns_binding_lookup_next(). Call rpc_binding_vector_free() if you have used either of these routines. The rpc_binding_free() routine frees individual elements of the vector. If an element is freed with this routine, the NULL element entry replaces it; rpc_binding_vector_free() ignores such an entry. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_free rpc_ns_binding_lookup_next rpc_server_inq_bindings 4 rpc_cs_binding_set_tags NAME rpc_cs_binding_set_tags - Places code set tags into a server binding handle Used by client applications. SYNOPSIS #include void rpc_cs_binding_set_tags( rpc_binding_handle_t *binding, unsigned32 sending_tag, unsigned32 desired_receiving_tag, unsigned16 sending_tag_max_bytes, error_status_t *status ); PARAMETERS Input/Output binding On input, specifies the server binding handle to modify with tag information. This handle is the binding handle returned by the rpc_ns_binding_import_next() or rpc_ns_binding_select() routine. On output, returns the server binding handle modified with code set tag information. The server stub retrieves the tag information from the binding handle and uses it to invoke the appropriate buffer sizing and code set conversion routines. Input sending_tag Specifies the code set value for the code set in which client data to be sent to the server is to be encoded. If the client is not sending any data, set this value to the client's current code set. This step prevents the code set conversion routine from being invoked. desired_receiving_tag Specifies the code set value for the code set in which the client prefers data to be encoded when sent back from the server. If the client is not planning to receive any data from the server, set this value to the server's current code set. This step prevents the code set conversion routine from being invoked. sending_tag_max_bytes Specifies the maximum number of bytes that a code set requires to encode one character. The value is the c_max_bytes value associated with the code set value (c_set) used as the sending_tag value. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok rpc_s_no_memory The routine can also return status codes generated by the rpc_rgy_get_codesets() routine. DESCRIPTION The rpc_cs_binding_set_tags() routine belongs to a set of DCE RPC routines for use by client and server applications that are transferring international character data in a heterogeneous character set and code sets environment. These routines are used to enable "automatic" code set conversion between client and server for character representations that are not part of the DCE Portable Character Set. Client applications use the rpc_cs_binding_set_tags() routine to add code sets tag information to the binding handle of a compatible server. The tag information specified in the routine is usually obtained from a character and code sets evaluation routine (which is typically a user-written routine). The sending_tag value identifies the code set encoding that the client is using to send international character data to the server. The desired_receiving_tag value indicates to the server the code set that the client prefers the server to use when sending return international character data. The sending_tag_max_bytes value is the number of bytes the sending code set uses to encode one character. Client applications that use the rpc_cs_eval_with_universal() or rpc_cs_eval_without_universal() routines do not need to call this routine because these routines set tag information in the server binding handle as part of their operation. Application developers who are writing their own character and code sets evaluation routines need to include code that sets tags in a server binding handle. The rpc_cs_binding_set_tags() routine provides this function and can be used in user-written evaluation routines, or alone if the application does not need to perform evaluation. In this case, the routine provides a short cut for application programmers whose applications do not need to evaluate for character and code set compatibility. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_cs_eval_with_universal rpc_cs_eval_without_universal rpc_cs_get_tags 4 rpc_cs_char_set_compat_check NAME rpc_cs_char_set_compat_check - Evaluates character set compatibility between a client and a server. Used by client applications. SYNOPSIS #include void rpc_cs_char_set_compat_check( unsigned32 client_rgy_code_set_value, unsigned32 server_rgy_code_set_value, error_status_t *status ); PARAMETERS Input client_rgy_code_set_value The registered hexadecimal value that uniquely identifies the code set that the client is using as its local code set. server_rgy_code_set_value The registered hexadecimal value that uniquely identifies the code set that the server is using as its local code set. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok rpc_s_ss_no_compat_charsets The routine can also return status codes from the dce_cs_rgy_to_loc() routine. DESCRIPTION The rpc_cs_char_set_compat_check() routine belongs to a set of DCE RPC routines for use by client and server applications that are transferring international character data in a heterogeneous character set and code sets environment. The rpc_cs_char_set_compat_check() routine provides a method for determining character set compatibility between a client and a server; if the server's character set is incompatible with that of the client, then connecting to that server is most likely not acceptable, since massive data loss would result from such a connection. The RPC routines that perform character and code sets evaluation use the rpc_cs_char_set_compat_check() routine in their character sets and code sets compatibility checking procedure. The routine takes the registered integer values that represent the code sets that the client and server are currently using and calls the code set registry to obtain the registered values that represent the character set(s) that the specified code sets support. If both client and server support just one character set, the routine compares client and server registered character set values to determine whether or not the sets are compatible. If they are not, the routine returns the status message rpc_s_ss_no_compat_charsets. If the client and server support multiple character sets, the routine determines whether at least two of the sets are compatible. If two or more sets match, the routine considers the character sets compatible, and returns a success status code to the caller. Client and server applications that use the DCE RPC code sets evaluation routines rpc_cs_eval_with_universal() and rpc_cs_eval_without_universal() do not need to call this routine explicitly because these DCE RPC routines call it on their behalf. Client applications that do not use the DCE RPC code sets evaluation routines can use the rpc_cs_char_set_compat_check() routine in their code sets evaluation code as part of their procedure for determining character and code set compatibility with a server. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_cs_eval_with_universal rpc_cs_eval_without_universal rpc_cs_get_tags rpc_ns_mgmt_read_codesets rpc_rgy_get_codesets 4 rpc_cs_eval_with_universal NAME rpc_cs_eval_with_universal - Evaluates a server's supported character sets and code sets during the server binding selection process Used indirectly by client applications. SYNOPSIS #include void rpc_cs_eval_with_universal( rpc_ns_handle_t binding_handle, idl_void_p_t eval_args, idl_void_p_t *context ); PARAMETERS Input binding_handle The server binding handle. eval_args An opaque data type that contains matching criteria that the routine uses to perform character and code sets compatibility evaluation. Input/Output context An opaque data type that contains search context to perform character and code sets compatibility evaluation. The routine returns the result of the evaluation in a field within context. DESCRIPTION The rpc_cs_eval_with_universal() routine is a DCE RPC character and code sets evaluation routine that can be added to an import context. The routine provides a mechanism for a client application that is passing character data in a heterogeneous character set and code sets environment to evaluate a server's character and code sets compatibility before establishing a connection with it. Client applications do not call rpc_cs_eval_with_universal() directly. Instead, they add it to the import context created by the rpc_ns_binding_import_begin() routine by calling the routine rpc_ns_import_ctx_add_eval() and specifying the routine name and the RPC server entry name to be evaluated. When the client application calls the rpc_ns_binding_import_next() routine to import compatible binding handles for servers, this routine calls rpc_cs_eval_with_universal(), which applies client-server code sets compatibility checking as another criteria for compatible binding selection. The rpc_cs_eval_with_universal() routine directs the rpc_ns_binding_import_next() routine to reject servers with incompatible character sets. If client and server character sets are compatible, but their supported code sets are not, the routine establishes tags that direct the client and/or server stubs to convert character data to the user-defined (if any) or default intermediate code set, which is the ISO10646 (or "universal") code set. Application programmers need not pay attention to the arguments of this routine. They only need to use the rpc_ns_import_ctx_add_eval() to set the routine, for example: rpc_ns_import_ctx_add_eval( &import_context, rpc_c_eval_type_codesets, (void *) nsi_entry_name, rpc_cs_eval_with_universal, NULL, &status ); Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_cs_eval_without_universal rpc_cs_get_tags rpc_ns_binding_import_begin rpc_ns_binding_import_done rpc_ns_binding_import_next rpc_ns_import_ctx_add_eval rpc_ns_mgmt_handle_set_exp_age 4 rpc_cs_eval_without_universal NAME rpc_cs_eval_without_universal - Evaluates a server's supported character sets and code sets during the server binding selection process Used indirectly by client applications. SYNOPSIS #include void rpc_cs_eval_without_universal( rpc_ns_handle_t binding_handle, idl_void_p_t eval_args, idl_void_p_t *context ); PARAMETERS Input binding_handle The server binding handle. eval_args An opaque data type that contains matching criteria that the routine uses to perform code sets compatibility evaluation. Input/Output context An opaque data type that contains search context to perform character and code sets compatibility evaluation. The routine returns the result of the evaluation in a field within context. DESCRIPTION The rpc_cs_eval_without_universal() routine is a DCE RPC character and code sets evaluation routine that can be added to an import context. The routine provides a mechanism for a client application that is passing character data in a heterogeneous character set and code sets environment to evaluate a server's character and code sets compatibility before establishing a connection with it. Client applications do not call rpc_cs_eval_without_universal() directly. Instead, they add it to the import context created by the rpc_ns_binding_import_begin() routine by calling the routine rpc_ns_import_ctx_add_eval() and specifying the routine name and the RPC server entry name to be evaluated. When the client application calls the rpc_ns_binding_import_next() routine to import compatible binding handles for servers, this routine calls rpc_cs_eval_without_universal(), which applies client-server code sets compatibility checking as another criteria for compatible binding selection. The rpc_cs_eval_without_universal() routine directs the rpc_ns_binding_import_next() routine to reject servers with incompatible character sets. The routine also directs the rpc_ns_binding_import_next() routine to reject servers whose supported code sets are incompatible with the client's supported code sets; that is, it does not resort to using an intermediate code set as a last resort. Application programmers need not pay attention to the arguments of this routine. They only need to use the rpc_ns_import_ctx_add_eval() to set the routine, for example: rpc_ns_import_ctx_add_eval( &import_context, rpc_c_eval_type_codesets, (void *) nsi_entry_name, rpc_cs_eval_without_universal, NULL, &status ); Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_cs_get_tags rpc_ns_binding_import_begin rpc_ns_binding_import_done rpc_ns_binding_import_next rpc_ns_import_ctx_add_eval rpc_ns_mgmt_handle_set_exp_age 4 rpc_cs_get_tags NAME rpc_cs_get_tags - Retrieves code set tags from a binding handle Used by client and server applications. SYNOPSIS #include void rpc_cs_get_tags( rpc_binding_handle_t binding, boolean32 server_side, unsigned32 *sending_tag, unsigned32 *desired_receiving_tag, unsigned32 *receiving_tag, error_status_t *status ); PARAMETERS Input binding Specifies the target binding handle from which to obtain the code set tag information. When called from the client stub, this value is the binding handle of a compatible server returned by the rpc_ns_binding_import_next() or rpc_ns_binding_select() routines. When called from the server stub, this value is a pointer to the tag information that the client stub passed in the RPC call. server_side Indicates whether a client stub or a server stub is calling the routine. desired_receiving_tag (Server stub only) Specifies the code set value for the code set in which the client prefers data to be encoded when sent back from the server. The client stub passes this value in the RPC call. If the routine is retrieving code set tags for an operation that does not specify a desired receiving tag parameter (the cs_drtag ACF parameter attribute has not been applied to one of the operation's parameters), this value is NULL. Output sending_tag (Client stub only) Specifies the code set value for the code set in which client data to be sent to the server is to be encoded. If the routine is retrieving code set tags for an operation that does not specify a sending tag parameter (the cs_stag ACF parameter attribute has not been applied to one of the operation's parameters), this value is NULL. desired_receving_tag (Client stub only) Specifies the code set value for the code set in which the client prefers to receive data sent back to it from the server. If the routine is retrieving code set tags for an operation that does not specify a desired receiving tag parameter (the cs_drtag ACF parameter attribute has not been applied to one of the operation's parameters), this value is NULL. receiving_tag (Server stub only) Specifies the code set value for the code set in which the server is to encode data to be sent back to the client. If the routine is retrieving code set tags for an operation that does not specify a receiving tag parameter (the cs_rtag ACF parameter attribute has not been applied to one of the operation's parameters), this value is NULL. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_ss_incompatible_codesets The server cannot handle the data in the code set that the client has specified. This status code will be returned if the application performs code set compatibility evaluation in the server stub. rpc_s_ss_invalid_codeset_tag The result of the client-side evaluation used an invalid code set tag. If code set compatibility evaluation is performed, error values can also be returned from rpc_rgy_get_codesets(), rpc_ns_binding_inq_entry_name(), and rpc_ns_mgmt_read_codesets(). DESCRIPTION The rpc_cs_get_tags() routine belongs to a set of DCE RPC routines for use by client and server applications that are transferring international character data in a heterogeneous character set and code sets environment. The rpc_cs_get_tags() routine is a DCE RPC routine that RPC stubs can use to retrieve the code set values to be used to "tag" international character data to be sent over the network. In general, the code set values to be used as tags are determined by a character and code sets evaluation routine, which is invoked from the client application code. However, application programmers can use other methods to establish values for code set tags. RPC stubs call the rpc_cs_get_tags() routine before they call the buffer sizing routines *_net_size() and the code set conversion routines _netcs(). The rpc_cs_get_tags() routine provides the stubs with code set values to use as input to the buffer sizing routines (to determine whether or not buffer storage needs to be allocated for conversion) and as input to the code set conversion routines (to determine whether conversion is necessary, and if so, which host code set converter to invoke). Client and server stubs call the rpc_cs_get_tags() routine before they marshall any data. When called from the client stub, the boolean value server_side is set to FALSE to indicate that the client stub has invoked the routine. The binding handle is the handle to a compatible server returned by the rpc_ns_binding_import_next() or rpc_ns_binding_select() routines. If the client has added a code sets evaluation routine to the binding import procedure (by calling the routine rpc_ns_import_ctx_add_eval()), the binding handle will contain the conversion method and the code set values to set for the client's sending tag and desired receiving tag. If the binding handle does not contain the results of an evaluation, the rpc_cs_get_tags() routine will perform the character/code sets evaluation within the client stub and set the client code set tag values itself. On the client side, the output of the routine is the code set value that represents the client's sending tag and the code set value that represents the client's desired receiving tag. If the conversion method is "client makes it right" (CMIR), the sending tag and desired receiving tags will be set to the code set value of the server's local code set. If the conversion method is "server makes it right" (SMIR), the sending tag and desired receiving tag will be set to the client's local code set value. If the conversion method is "receiver makes it right" (RMIR), the sending tag is the client's code set, and the desired receiving tag is the server's code set. When called from the server stub, the boolean value server_side is set to TRUE to indicate that the server stub has invoked the routine. The binding handle is a pointer to the tag data sent by the client stub. The server stub specifies the code set value given in the client's desired receiving tag as input to the routine. The rpc_cs_get_tags() routine sets the code set value in desired_receiving_tag to receiving_tag and returns this value as output to the server stub. The server stub will then use the code set value in receiving_tag as the code set to use for data it sends back to the client. Application programmers who want their applications to use the rpc_cs_get_tags() routine to retrieve code set tag information as part of the automatic code set conversion process specify the routine name as the argument to the ACF attribute cs_tag_rtn when developing their internationalized RPC application. Application programmers can also write their own code set tags retrieval routine that RPC stubs can call; in this case, they specify the name of this routine as the argument to the ACF attribute instead of specifying the DCE RPC routine rpc_cs_get_tags(). Application programmers can also use the automatic code conversion mechanism, but design their applications so that the code set tags are set explicitly in the application instead of in the stubs. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: cs_byte_from_netcs cs_byte_local_size cs_byte_net_size cs_byte_to_netcs wchar_t_from_netcs wchar_t_local_size wchar_t_net_size wchar_t_to_netcs Books: OSF DCE Application Development Guide-Core Components. 4 rpc_ep_register NAME rpc_ep_register - Adds to, or replaces, server address information in the local endpoint map Used by server applications. SYNOPSIS #include void rpc_ep_register( rpc_if_handle_t if_handle, rpc_binding_vector_t *binding_vec, uuid_vector_t *object_uuid_vec, unsigned_char_t *annotation, unsigned32 *status ); PARAMETERS Input if_handle Specifies an interface specification to register with the local endpoint map. binding_vec Specifies a vector of binding handles over which the server can receive remote procedure calls. object_uuid_vec Specifies a vector of object UUIDs that the server offers. The server application constructs this vector. Supply the value NULL to indicate there are no object UUIDs to register. annotation Defines a character string comment applied to each cross product element added to the local endpoint map. The string can be up to 64 characters long, including the NULL terminating character. Specify NULL or the string \0 if there is no annotation string. The string is used by applications for informational purposes only. The RPC runtime does not use this string to determine which server instance a client communicates with, or for enumerating endpoint map elements. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. ept_s_cant_access Error reading endpoint database. ept_s_cant_create Error creating endpoint database. ept_s_cant_perform_op Cannot perform requested operation. ept_s_database_invalid Endpoint map database invalid. ept_s_invalid_entry Invalid database entry. ept_s_update_failed Update failed. rpc_s_comm_failure Communications failure. rpc_s_invalid_binding Invalid binding handle. rpc_s_no_bindings No bindings. rpc_s_wrong_kind_of_binding Wrong kind of binding for operation. DESCRIPTION The rpc_ep_register() routine adds elements to, or replaces elements in, the local host's endpoint map. Each element in the local endpoint map logically contains the following: + Interface ID, consisting of an interface UUID and versions (major and minor) + Binding information + Object UUID (optional) + Annotation (optional) A server uses this routine, instead of rpc_ep_register_no_replace(), when only a single instance of the server runs on the server's host. Use this routine if, at any time, no more than one server instance offers the same interface UUID, object UUID, and protocol sequence. When local endpoint map elements are not replaced, obsolete elements accumulate each time a server instance stops running without calling rpc_ep_unregister(). Periodically the DCE Host Daemon identifies these obsolete elements and removes them. However, during the time between these removals the obsolete elements increase the chance that a client will receive endpoints to nonexistent servers. The client then wastes time trying to communicate with these servers before obtaining another endpoint. Using this routine to replace any existing local endpoint map elements reduces the chance that a client will receive the endpoint of a nonexistent server instance. Suppose an existing element in the local endpoint map matches the interface UUID, binding information exclusive of the endpoint, and object UUID of an element this routine provides. The routine changes the endpoint map according to the elements' interface major and minor version numbers, as shown in the following table: Existing Element Relationship Provided Element Routine's Action ______________________________________________________________________ Major version # Not equal to Major version # Ignores minor ver- sion number rela- tionship and adds a new endpoint map element. The existing element remains unchanged. Major version # Equal to Major version # Acts according to the minor version number relation- ship. Minor version # Equal to Minor version # Replaces the end- point of the existing element based on the pro- vided information. Minor version # Less than Minor version # Replaces the existing element based on the pro- vided information. Minor version # Greater than Minor version # Ignores the pro- vided information. The existing ele- ment remains unchanged. For example, suppose under these circumstances that the existing interface version number is 1.3 (major.minor) and the provided version number is 2.0. The routine adds a new endpoint map element with interface version number 2.0 and does not change the element with version number 1.3. However, if the existing interface version number is 1.5 and the provided version number is 1.4, the routine does not change the endpoint map. A server program calls this routine to register endpoints that have been specified by calling any of the following routines: + rpc_server_use_all_protseqs() + rpc_server_use_protseq() + rpc_server_use_protseq_ep() A server that calls only the rpc_server_use_all_protseqs_if() or rpc_server_use_protseq_if() routines does not need to call this routine. In such cases, the client's runtime uses an endpoint from the client's interface specification to fill in a partially bound binding handle. However, it is recommended that you also register well-known endpoints that the server specifies (registering endpoints from interface definitions is unnecessary). If the server also exports to the name service database, the server calls this routine with the same if_handle, binding_vec and object_uuid_vec parameters as the server uses when calling the rpc_ns_binding_export() routine. The rpc_ep_register() routine communicates with the DCE Host Daemon (dced), which in turn communicates with the local endpoint map. The routine communicates using one of the protocol sequences specified in one of the binding handles in binding_vec. Attempting to register a binding that specifies a protocol sequence that the DCE Host daemon is not listening on results in the failure of rpc_ep_register(). The routine indicates this failure by placing the value rpc_s_comm_failure into status. For information about how the endpoint map service selects an element for an interface ID and an object UUID, see the RPC information in the OSF DCE Application Development Guide. This guide explains how the endpoint map service searches for the endpoint of a server that is compatible with a client. If the client supplies a non-nil object UUID that is not in the endpoint map, or the client supplies a nil object UUID, the search can succeed, but only if the server has registered a nil object UUID using the rpc_ep_register() or rpc_ep_register_no_replace() routines. The object_uuid_vec parameter can contain both nil and non-nil object UUIDs for the routine to place into endpoint map elements. For an explanation of how a server can establish a client/server relationship without using the local endpoint map, see the explanation of a string binding in the rpc_intro reference page. This routine creates a cross product from the if_handle, binding_vec and object_uuid_vec parameters, and adds each element in the cross product as a separate registration in the local endpoint map. If you supply NULL to object_uuid_vec, the corresponding elements in the cross product contain a nil object UUID. For example, suppose that if_handle has the value ifhand, binding_vec has the values b1, b2, b3, and object_uuid_vec has the values u1, u2, u3, u4.The resulting 12 elements in the cross product are as follows: (ifhand,b1,u1) (ifhand,b1,u2) (ifhand,b1,u3) (ifhand,b1,u4) (ifhand,b2,u1) (ifhand,b2,u2) (ifhand,b2,u3) (ifhand,b2,u4) (ifhand,b3,u1) (ifhand,b3,u2) (ifhand,b3,u3) (ifhand,b3,u4) (An annotation string is part of each of these 12 elements.) RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ep_register_no_replace rpc_ep_resolve_binding rpc_ep_unregister rpc_mgmt_ep_unregister rpc_ns_binding_export rpc_server_inq_bindings rpc_server_use_all_protseqs rpc_server_use_all_protseqs_if rpc_server_use_protseq rpc_server_use_protseq_ep rpc_server_use_protseq_if Books: OSF DCE Application Development Guide. 4 rpc_ep_register_no_replace NAME rpc_ep_register_no_replace - Adds to server address information in the local endpoint map Used by server applications. SYNOPSIS #include void rpc_ep_register_no_replace( rpc_if_handle_t if_handle, rpc_binding_vector_t *binding_vec, uuid_vector_t *object_uuid_vec, unsigned_char_t *annotation, unsigned32 *status ); PARAMETERS Input if_handle Specifies an interface specification to register with the local endpoint map. binding_vec Specifies a vector of binding handles over which the server can receive remote procedure calls. object_uuid_vec Specifies a vector of object UUIDs that the server offers. The server application constructs this vector. Supply the value NULL to indicate there are no object UUIDs to register. annotation Defines a character string comment applied to each cross-product element added to the local endpoint map. The string can be up to 64 characters long, including the NULL terminating character. Specify NULL or the string \0 if there is no annotation string. The string is used by applications for informational purposes only. The RPC runtime does not use this string to determine which server instance a client communicates with, or for enumerating endpoint map elements. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. ept_s_cant_access Error reading endpoint database. ept_s_cant_create Error creating endpoint database. ept_s_cant_perform_op Cannot perform requested operation. ept_s_database_invalid Endpoint map database invalid. ept_s_invalid_entry Invalid database entry. ept_s_update_failed Update failed. rpc_s_comm_failure Communications failure. rpc_s_invalid_binding Invalid binding handle. rpc_s_no_bindings No bindings. rpc_s_wrong_kind_of_binding Wrong kind of binding for operation. DESCRIPTION The rpc_ep_register_no_replace() routine adds elements to the local host's endpoint map. The routine does not replace existing elements. Otherwise, this routine is identical to rpc_ep_register(). Each element in the local endpoint map logically contains the following: + Interface ID, consisting of an interface UUID and versions (major and minor) + Binding information + Object UUID (optional) + Annotation (optional) A server uses this routine, instead of rpc_ep_register(), when multiple instances of the server run on the same host. Use this routine if, at any time, more than one server instance offers the same interface UUID, object UUID, and protocol sequence. Since this routine does not replace elements, calling servers must unregister (that is, remove) themselves before they stop running. Otherwise, when local endpoint map elements are not replaced, obsolete elements accumulate each time a server instance stops running without calling rpc_ep_unregister(). Periodically the DCE Host Daemon identifies obsolete elements and removes them from the local endpoint map. However, during the time between these removals, the obsolete elements increase the chance that a client will receive endpoints to nonexistent servers.The client then wastes time trying to communicate with these servers before obtaining another endpoint. A server program calls this routine to register endpoints that were specified by calling any of the following routines: + rpc_server_use_all_protseqs() + rpc_server_use_protseq() + rpc_server_use_protseq_ep() A server that calls only the rpc_server_use_all_protseqs_if() or rpc_server_use_protseq_if() routine does not need to call this routine. In such cases, the client's runtime uses an endpoint from the client's interface specification to fill in a partially bound binding handle. However, it is recommended that you also register well-known endpoints that the server specifies (registering endpoints from interface definitions is unnecessary). If the server also exports to the name service database, the server calls this routine with the same if_handle, binding_vec and object_uuid_vec parameters as the server uses when calling the rpc_ns_binding_export() routine. The rpc_ep_register_no_replace() routine communicates with the DCE Host Daemon (dced), which in turn communicates with the local endpoint map. The routine communicates using one of the protocol sequences specified in one of the binding handles in binding_vec. Attempting to register a binding that specifies a protocol sequence that the DCE Host daemon is not listening on results in the failure of rpc_ep_register_no_replace(). The routine indicates this failure by placing the value rpc_s_comm_failure into status. For information about how the endpoint map service selects an element for an interface ID and an object UUID, see the RPC information in the OSF DCE Application Development Guide. This guide explains how the endpoint map service searches for the endpoint of a server that is compatible with a client. If the client supplies a non-nil object UUID that is not in the endpoint map, or the client supplies a nil object UUID, the search can succeed, but only if the server has registered a nil object UUID using the rpc_ep_register_no_replace() or rpc_ep_register() routine. The object_uuid_vec parameter can contain both nil and non-nil object UUIDs for the routine to place into endpoint map elements. For an explanation of how a server can establish a client/server relationship without using the local endpoint map, see the explanation of a string binding in the rpc_intro reference page. This routine creates a cross-product from the if_handle, binding_vec and object_uuid_vec parameters, and adds each element in the cross- product as a separate registration in the local endpoint map. If you supply NULL to object_uuid_vec, the corresponding elements in the cross-product contain a nil object UUID. The rpc_ep_register() routine's reference page summarizes the contents of an element in the local endpoint map. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ep_register rpc_ep_resolve_binding rpc_ep_unregister rpc_mgmt_ep_unregister rpc_ns_binding_export rpc_server_inq_bindings rpc_server_use_all_protseqs rpc_server_use_all_protseqs_if rpc_server_use_protseq rpc_server_use_protseq_ep rpc_server_use_protseq_if Books: OSF DCE Application Development Guide. 4 rpc_ep_resolve_binding NAME rpc_ep_resolve_binding - Resolves a partially bound server binding handle into a fully bound server binding handle Used by client and management applications. SYNOPSIS #include void rpc_ep_resolve_binding( rpc_binding_handle_t binding, rpc_if_handle_t if_handle, unsigned32 *status ); PARAMETERS Input/Output binding Specifies a partially bound server binding handle to resolve into a fully bound server binding handle. if_handle Contains a stub-generated data structure that specifies the interface of interest. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. ept_s_not_registered No entries found. rpc_s_invalid_binding Invalid binding handle. rpc_s_wrong_kind_of_binding Wrong kind of binding for operation. rpc_s_rpcd_comm_failure Communications failure while trying to reach the endpoint map. DESCRIPTION An application calls the rpc_ep_resolve_binding() routine to resolve a partially bound server binding handle into a fully bound server binding handle. Resolving binding handles requires an interface UUID and an object UUID. The object UUID can be a nil UUID. The RPC runtime requests the DCE Host Daemon's Endpoint Mapper Service, on the host that the binding parameter specifies, to look up an endpoint for a compatible server instance. The Endpoint Mapper Service finds the endpoint by looking in the local endpoint map for the interface UUID from the if_handle parameter and for the object UUID in the binding parameter. The rpc_ep_resolve_binding() routine depends on whether the specified binding handle is partially bound or fully bound. When the application specifies a partially bound handle, the routine produces the following results: + If no compatible server instances are registered in the local endpoint map, the routine returns the ept_s_not_registered status code. + If one compatible server instance is registered in the local endpoint map, the routine returns a fully bound binding handle in binding and the rpc_s_ok status code. + If more than one compatible server instance is registered in the local endpoint map, the routine randomly selects one. It then returns the corresponding fully bound binding handle in binding and the rpc_s_ok status code. When the application specifies a fully bound binding handle, the routine returns the specified binding handle in binding and the rpc_s_ok status code. The routine makes no request of the DCE Host daemon. In neither the partially bound case nor the fully bound case does the routine contact a compatible server instance. Using This Routine For each server instance, the RPC runtime automatically provides routines (the rpc_mgmt_* routines) that form an RPC management interface. If a server instance registers any application-provided interfaces, the RPC runtime automatically registers the RPC-provided management interface with the local endpoint map for that server instance. An application can call rpc_ep_resolve_binding() at any time with either a partially bound or a fully bound handle. However, applications typically call this routine to avoid calling a routine in the management interface with a partially bound handle. An application can have a partially bound binding handle at the following times: + After importing a binding handle. + After resetting a binding handle. + After converting a string binding without an endpoint to a binding handle. If an application calls an application-provided remote procedure using a partially bound handle, the RPC runtime automatically asks the DCE Host daemon to resolve the binding handle into a fully bound handle. This fully bound binding handle corresponds to the RPC interface of the called remote procedure and the requested object, if any. The application can then use this fully bound handle to make remote management calls, so calling the rpc_ep_resolve_binding() routine is unnecessary. When a high proportion of all servers in an environment offers the same interface, the interface is known as a pervasive one. The RPC management interface is a pervasive interface in all environments that use DCE RPC. Using this routine to unambiguously locate compatible server instances applies to application-pervasive interfaces as well as to the RPC management interface. Partially Bound Handles with a Non-nil Object UUID If the application has a partially bound handle with a non-nil object UUID, the application can decide not to call the rpc_ep_resolve_binding() routine before calling a procedure in the management interface. In this case the remote management call is sent to a server instance, registered on the remote host, that offers that object UUID. After completing the remote management call, the application has a fully bound handle to that server instance. The server instance that the handle specifies probably offers the non-management interfaces of interest to the calling application. However, if you want to be certain of obtaining a fully bound handle to a server instance that offers the interfaces needed for later remote procedure calls, call the rpc_ep_resolve_binding() routine. Partially Bound Handles with a Nil Object UUID When an application makes a remote procedure or management call using a partially bound handle with a nil object UUID, the DCE Host daemon searches for a compatible server instance. The search is based on the nil object UUID and the UUID of the interface to which the call belongs. All server instances that register any RPC interface automatically offer the RPC management interface. When an application makes a remote management call using a partially bound handle with a nil object UUID, the DCE Host daemon on the remote host cannot distinguish among server instances registered in the local endpoint map. When the DCE Host daemon cannot distinguish among these instances it selects any server instance. After completing the remote management call, the calling application has a fully bound handle. However, the server instance that the handle represents probably does not offer the non-management interfaces that interest the application. The remote RPC management routines avoid this ambiguity. They do this by returning the status rpc_s_binding_incomplete if the provided binding handle is a partially bound one with a nil object UUID. An application wanting to contact servers that have exported and registered interfaces with a nil object UUID calls routine rpc_ep_resolve_binding(). The application obtains a fully bound binding handle for calling remote management procedures in a server instance that also offers the remote procedures in the application- specific interface. Note that an application that wants to manage all the server instances on a host does not call rpc_ep_resolve_binding(). Instead, the application obtains fully bound binding handles for each server instance by calling rpc_mgmt_ep_elt_inq_begin(), rpc_mgmt_ep_elt_inq_next(), and rpc_mgmt_ep_elt_inq_done(). RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ep_register rpc_ep_register_no_replace rpc_mgmt_ep_elt_inq_begin rpc_mgmt_ep_elt_inq_done rpc_mgmt_ep_elt_inq_next rpc_binding_from_string_binding rpc_binding_reset 4 rpc_ep_unregister NAME rpc_ep_unregister - Removes server address information from the local endpoint map Used by server applications. SYNOPSIS #include void rpc_ep_unregister( rpc_if_handle_t if_handle, rpc_binding_vector_t *binding_vec, uuid_vector_t *object_uuid_vec, unsigned32 *status ); PARAMETERS Input if_handle Specifies an interface specification to remove (that is, unregister) from the local endpoint map. binding_vec Specifies a vector of binding handles to remove. object_uuid_vec Specifies a vector of object UUIDs to remove. The server application constructs this vector. This routine removes all local endpoint map elements that match the specified if_handle parameter, binding_vec parameter, and object UUIDs. This is an optional parameter. The value NULL indicates there are no object UUIDs to remove. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. ept_s_cant_access Error reading endpoint database. ept_s_cant_create Error creating endpoint database. ept_s_cant_perform_op Cannot perform requested operation. ept_s_database_invalid Endpoint map database invalid. ept_s_invalid_entry Invalid database entry. ept_s_update_failed Update failed. rpc_s_invalid_binding Invalid binding handle. rpc_s_no_bindings No bindings. rpc_s_wrong_kind_of_binding Wrong kind of binding for operation. DESCRIPTION The rpc_ep_unregister() routine removes elements from the local host's endpoint map. A server application calls this routine only if the server has registered endpoints previously and the server wishes to remove that address information from the local endpoint map. A server program is able to remove its own local endpoint map elements (server address information) based on either of the following: + The interface specification. + The interface specification and the object UUIDs of resources offered. The server calls the rpc_server_inq_bindings() routine to obtain the required binding_vec parameter. To remove selected endpoints, the server can remove individual elements from binding_vec before calling this routine. (See the explanation of a binding vector in the rpc_intro reference page for more information about removing a single element from a vector of binding handles.) This routine creates a cross product from the if_handle, binding_vec and object_uuid_vec parameters and removes each element in the cross product from the local endpoint map. The rpc_ep_register() routine's reference page summarizes the contents of a cross product in the local endpoint map. Servers must always call the rpc_ep_unregister() routine to remove their endpoints from the local endpoint map before they exit. Otherwise, stale information will be in the local endpoint map. However, if a server prematurely removes endpoints (the server is not in the process of exiting), clients that do not already have fully bound binding handles to the server will not be able to send remote procedure calls to the server. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ep_register rpc_ep_register_no_replace rpc_mgmt_ep_unregister rpc_ns_binding_unexport rpc_server_inq_bindings 4 rpc_if_id_vector_free NAME rpc_if_id_vector_free - Frees a vector and the interface identifier structures it contains Used by client, server, or management applications. SYNOPSIS #include void rpc_if_id_vector_free( rpc_if_id_vector_t **if_id_vector, unsigned32 *status ); PARAMETERS Input/Output if_id_vector Specifies the address of a pointer to a vector of interface information. On return the pointer is set to NULL. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their explanations are as follows: rpc_s_ok Success. rpc_s_invalid_arg Invalid argument. DESCRIPTION The rpc_if_id_vector_free() routine frees the memory used to store a vector of interface identifiers. This includes memory used by the interface identifiers and the vector itself. On return this routine sets the if_id_vector parameter to NULL. To obtain a vector of interface identifiers, call rpc_ns_mgmt_entry_inq_if_ids() or rpc_mgmt_inq_if_ids(). Call rpc_if_id_vector_free() if you have used either of these routines. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_if_inq_id rpc_mgmt_inq_if_ids rpc_ns_mgmt_entry_inq_if_ids 4 rpc_if_inq_id NAME rpc_if_inq_id - Returns the interface identifier for an interface specification Used by client or server applications. SYNOPSIS #include void rpc_if_inq_id( rpc_if_handle_t if_handle, rpc_if_id_t *if_id, unsigned32 *status ); PARAMETERS Input if_handle Represents a stub-generated data structure that specifies the interface specification to inquire about. Output if_id Returns the interface identifier. The application provides memory for the returned data. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status code and its meaning is as follows: rpc_s_ok Success. DESCRIPTION An application calls the rpc_if_inq_id() routine to obtain a copy of the interface identifier from the provided interface specification. The returned interface identifier consists of the interface UUID and interface version numbers (major and minor) specified in the DCE IDL file's interface specification. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_if_id_vector_free rpc_mgmt_inq_if_ids rpc_ns_mgmt_entry_inq_if_ids 4 rpc_mgmt_ep_elt_inq_begin NAME rpc_mgmt_ep_elt_inq_begin - Creates an inquiry context for viewing the elements in an endpoint map Used by management applications. SYNOPSIS #include void rpc_mgmt_ep_elt_inq_begin( rpc_binding_handle_t ep_binding, unsigned32 inquiry_type, rpc_if_id_t *if_id, unsigned32 vers_option, uuid_t *object_uuid, rpc_ep_inq_handle_t *inquiry_context, unsigned32 *status ); PARAMETERS Input ep_binding Specifies the host whose local endpoint map elements you receive. To receive elements from the same host as the calling application, specify NULL. To receive local endpoint map elements from another host, specify a server binding handle for that host. You can specify the same binding handle you are using to make other remote procedure calls. The object UUID associated with this parameter must be a nil UUID. If you specify a non-nil UUID, the routine fails with the status code ept_s_cant_perform_op. Other than the host information and object UUID, all information in this parameter is ignored. inquiry_type Specifies an integer value that indicates the type of inquiry to perform on the local endpoint map. The following list shows the valid inquiry types: Valid Inquiries on Local Endpoint Maps _____________________________________________________________________ Value Description _____________________________________________________________________ rpc_c_ep_all_elts Returns every element from the local endpoint map. The if_id, vers_option, and object_uuid parameters are ignored. rpc_c_ep_match_by_if Searches the local endpoint map for those elements that contain the inter- face identifier specified by the if_id and vers_option values. The object_uuid parameter is ignored. rpc_c_ep_match_by_obj Searches the local endpoint map for those elements that contain the object UUID specified by the object_uuid param- eter. The if_id and vers_option parame- ters are ignored. rpc_c_ep_match_by_both Searches the local endpoint map for those elements that contain the inter- face identifier and object UUID speci- fied by the if_id, vers_option, and object_uuid parameters. Specifies the interface identifier of the local endpoint map elements to be returned by the rpc_mgmt_ep_elt_inq_next() routine. Use this parameter only when specifying a value of rpc_c_ep_match_by_if or rpc_c_ep_match_by_both for the inquiry_type parameter. Otherwise, this parameter is ignored and the value NULL can be specified. Specifies how the rpc_mgmt_ep_elt_inq_next() routine uses the if_id parameter. Use this parameter only when specifying a value of rpc_c_ep_match_by_if or rpc_c_ep_match_by_both for the inquiry_type parameter. Otherwise, this parameter is ignored and a 0 (zero) value can be specified. The following list presents the valid values for this parameter: Valid values of vers_option _____________________________________________________________________ Value Description _____________________________________________________________________ rpc_c_vers_all Returns local endpoint map elements that offer the specified interface UUID, regardless of the version numbers. For this value, specify 0 (zero) for both the major and minor versions in if_id. rpc_c_vers_compatible Returns local endpoint map elements that offer the same major version of the specified interface UUID and a minor version greater than or equal to the minor version of the specified interface UUID. rpc_c_vers_exact Returns local endpoint map elements that offer the specified version of the specified interface UUID. rpc_c_vers_major_only Returns local endpoint map elements that offer the same major version of the specified interface UUID (ignores the minor version). For this value, specify 0 (zero) for the minor version in if_id. rpc_c_vers_upto Returns local endpoint map elements that offer a version of the specified inter- face UUID less than or equal to the specified major and minor version. (For example, suppose if_id contains V2.0 and the local endpoint map contained ele- ments with the following versions: V1.3, V2.0, and V2.1. The rpc_mgmt_ep_elt_inq_next routine returns the elements with V1.3 and V2.0.) Specifies the object UUID that rpc_mgmt_ep_elt_inq_next() looks for in local endpoint map elements. This parameter is used only when you specify a value of rpc_c_ep_match_by_obj or rpc_c_ep_match_by_both for the inquiry_type parameter. Otherwise, this parameter is ignored and you can supply NULL to specify a nil UUID. Output inquiry_context Returns an inquiry context for use with the rpc_mgmt_ep_elt_inq_next() and rpc_mgmt_ep_elt_inq_done() routines. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_invalid_inquiry_context Invalid inquiry context. rpc_s_invalid_inquiry_type Invalid inquiry type. rpc_s_invalid_vers_option Invalid version option. rpc_s_wrong_kind_of_binding Wrong kind of binding for operation. DESCRIPTION The rpc_mgmt_ep_elt_inq_begin() routine creates an inquiry context for viewing server address information stored in the local endpoint map. Using the inquiry_type and vers_option parameters, an application specifies which of the following local endpoint map elements are returned from calls to the rpc_mgmt_ep_elt_inq_next() routine: + All elements. + Those elements with the specified interface identifier. + Those elements with the specified object UUID. + Those elements with both the specified interface identifier and object UUID. Before calling the rpc_mgmt_ep_elt_inq_next() routine, the application must first call this routine to create an inquiry context. After viewing the local endpoint map elements, the application calls the rpc_mgmt_ep_elt_inq_done() routine to delete the inquiry context. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ep_register rpc_ep_register_no_replace rpc_ep_unregister rpc_mgmt_ep_elt_inq_done rpc_mgmt_ep_elt_inq_next rpc_mgmt_ep_unregister 4 rpc_mgmt_ep_elt_inq_done NAME rpc_mgmt_ep_elt_inq_done - Deletes the inquiry context for viewing the elements in an endpoint map Used by management applications. SYNOPSIS #include void rpc_mgmt_ep_elt_inq_done( rpc_ep_inq_handle_t *inquiry_context, unsigned32 *status ); PARAMETERS Input/Output inquiry_context Specifies the inquiry context to delete. (An inquiry context is created by calling rpc_mgmt_ep_elt_inq_begin().) Returns the value NULL. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_invalid_inquiry_context Invalid inquiry context. DESCRIPTION The rpc_mgmt_ep_elt_inq_done() routine deletes an inquiry context. The rpc_mgmt_ep_elt_inq_begin() routine created the inquiry context. An application calls this routine after viewing local endpoint map elements using the rpc_mgmt_ep_elt_inq_next() routine. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_mgmt_ep_elt_inq_begin rpc_mgmt_ep_elt_inq_next 4 rpc_mgmt_ep_elt_inq_next NAME rpc_mgmt_ep_elt_inq_next - Returns one element from an endpoint map Used by management applications. SYNOPSIS #include void rpc_mgmt_ep_elt_inq_next( rpc_ep_inq_handle_t inquiry_context, rpc_if_id_t *if_id, rpc_binding_handle_t *binding, uuid_t *object_uuid, unsigned_char_t **annotation, unsigned32 *status ); PARAMETERS Input inquiry_context Specifies an inquiry context. This inquiry context is returned from the rpc_mgmt_ep_elt_inq_begin() routine. Output if_id Returns the interface identifier of the local endpoint map element. binding Returns the binding handle from the local endpoint map element. Specify NULL to prevent the routine from returning this parameter. In this case the application does not call the rpc_binding_free() routine. object_uuid Returns the object UUID from the local endpoint map element. Specify NULL to prevent the routine from returning this parameter. annotation Returns the annotation string for the local endpoint map element. If there is no annotation string in the local endpoint map element, the string \0 is returned. Specify NULL to prevent the routine from returning this argument. In this case the application does not call the rpc_string_free() routine. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. ept_s_cant_perform_op Cannot perform the requested operation. rpc_s_comm_failure Communications failure. ept_s_database_invalid Endpoint map database invalid. rpc_s_fault_context_mismatch Fault context mismatch. ept_s_invalid_context Invalid inquiry type for this context. ept_s_invalid_entry Invalid database entry. rpc_s_invalid_arg Invalid argument. rpc_s_invalid_inquiry_context Invalid inquiry context. rpc_s_invalid_inquiry_type Invalid inquiry type. rpc_s_no_more_elements No more elements. DESCRIPTION The rpc_mgmt_ep_elt_inq_next() routine returns one element from the local endpoint map. Regardless of the selector value specified for the inquiry_type parameter in rpc_mgmt_ep_elt_inq_begin(), this routine returns all the components of a selected local endpoint map element. The rpc_ep_register() routine's reference page summarizes the contents of an element in the local endpoint map. An application can view all the selected local endpoint map elements by repeatedly calling the rpc_mgmt_ep_elt_inq_next() routine. When all the elements have been viewed, this routine returns an rpc_s_no_more_elements status. The returned elements are unordered. If a remote endpoint map contains elements that include a protocol sequence that your system does not support, this routine does not return the elements. (A protocol sequence is part of the binding information component of an endpoint map element.) To receive all possible elements from a remote endpoint map, your application must run on a system that supports the protocol sequences included in the elements. For example, if your system does not support protocol sequence ncacn_ip_tcp and a remote endpoint map contains elements that include this protocol sequence, this routine does not return these elements to your application. If your application ran on a system that supported protocol sequence ncacn_ip_tcp, this routine would return the elements. The RPC runtime allocates memory for the returned binding and the annotation string on each call to this routine. The application calls the rpc_binding_free() routine for each returned binding and the rpc_string_free() routine for each returned annotation string. After viewing the local endpoint map's elements, the application must call the rpc_mgmt_ep_elt_inq_done() routine to delete the inquiry context. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_free rpc_ep_register rpc_ep_register_no_replace rpc_mgmt_ep_elt_begin rpc_mgmt_ep_elt_done rpc_string_free 4 rpc_mgmt_ep_unregister NAME rpc_mgmt_ep_unregister - Removes server address information from an endpoint map Used by management applications. SYNOPSIS #include void rpc_mgmt_ep_unregister( rpc_binding_handle_t ep_binding, rpc_if_id_t *if_id, rpc_binding_handle_t binding, uuid_t *object_uuid, unsigned32 *status ); PARAMETERS Input ep_binding Specifies the host whose local endpoint map elements you unregister (that is, remove). To remove elements from the same host as the calling application, specify NULL. To remove local endpoint map elements from another host, specify a server binding handle for that host. You can specify the same binding handle you are using to make other remote procedure calls. The object UUID associated with this parameter must be a nil UUID. If you specify a non-nil UUID, the routine fails with the status code ept_s_cant_perform_op. Other than the host information and object UUID, all information in this parameter is ignored. if_id Specifies the interface identifier to remove from the local endpoint map. binding Specifies the binding handle to remove. object_uuid Specifies an optional object UUID to remove. The value NULL indicates there is no object UUID to consider in the removal. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. ept_s_cant_access Error reading the endpoint database. ept_s_cant_perform_op Cannot perform the requested operation. rpc_s_comm_failure Communications failure. ept_s_database_invalid Endpoint map database is invalid. ept_s_invalid_entry Invalid database entry. ept_s_not_registered No entries found. ept_s_update_failed Update failed. rpc_s_invalid_binding Invalid binding handle. rpc_s_no_interfaces No interfaces registered. rpc_s_wrong_kind_of_binding Wrong kind of binding for operation. DESCRIPTION The rpc_mgmt_ep_unregister() routine unregisters (that is, removes) an element from a local endpoint map. A management program calls this routine to remove addresses of servers that are no longer available, or to remove addresses of servers that support objects that are no longer offered. Use this routine cautiously; removing elements from the local endpoint map may make servers unavailable to client applications that do not already have a fully bound binding handle to the server. A management application calls the rpc_mgmt_ep_inq_next() routine to view local endpoint map elements. The application can then remove the elements using the rpc_mgmt_ep_unregister() routine. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ep_register rpc_ep_register_no_replace rpc_ns_binding_unexport rpc_mgmt_ep_elt_inq_begin rpc_mgmt_ep_elt_inq_done rpc_mgmt_ep_elt_inq_next 4 rpc_mgmt_inq_com_timeout NAME rpc_mgmt_inq_com_timeout - Returns the communications time-out value in a binding handle Used by client applications. SYNOPSIS #include void rpc_mgmt_inq_com_timeout( rpc_binding_handle_t binding, unsigned32 *timeout, unsigned32 *status ); PARAMETERS Input binding Specifies a server binding handle. Output timeout Returns the communications time-out value from the binding parameter. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_invalid_binding Invalid binding handle. rpc_s_wrong_kind_of_binding Wrong kind of binding for operation. DESCRIPTION The rpc_mgmt_inq_com_timeout() routine returns the communications timeout value in a server binding handle. The time-out value specifies the relative amount of time to spend trying to communicate with the server. Depending on the protocol sequence for the specified binding handle, the value in timeout acts only as advice to the RPC runtime. The rpc_mgmt_set_com_timeout reference page explains the time-out values returned in timeout. To change the timeout value, a client calls rpc_mgmt_set_com_timeout(). RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_mgmt_set_com_timeout 4 rpc_mgmt_inq_dflt_protect_level NAME rpc_mgmt_inq_dflt_protect_level - Returns the default protection level for an authentication service Used by client and server applications. SYNOPSIS #include void rpc_mgmt_inq_dflt_protect_level( unsigned32 authn_svc, unsigned32 *protect_level, unsigned32 *status ); PARAMETERS Input authn_svc Specifies the authentication service for which to return the default protection level. The supported authentication services are as follows: rpc_c_authn_none No authentication. rpc_c_authn_dce_secret DCE shared-secret key authentication. rpc_c_authn_dce_public DCE public key authentication (reserved for future use). rpc_c_authn_default DCE default authentication service. Output protect_level Returns the default protection level for the specified authentication service. The protection level determines the degree to which authenticated communications between the client and the server are protected. The possible protection levels are as follows: rpc_c_protect_level_default Uses the default protection level for the specified authentication service. rpc_c_protect_level_none Performs no protection. rpc_c_protect_level_connect Performs protection only when the client establishes a relationship with the server. rpc_c_protect_level_call Performs protection only at the beginning of each remote procedure call when the server receives the request. rpc_c_protect_level_pkt Ensures that all data received is from the expected client. rpc_c_protect_level_pkt_integ Ensures and verifies that none of the data transferred between client and server has been modified. rpc_c_protect_level_pkt_privacy Performs protection as specified by all of the previous levels and also encrypts each remote procedure call argument value. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_unknown_authn_service Unknown authentication service. DESCRIPTION The rpc_mgmt_inq_dflt_protect_level() routine returns the default protection level for the specified authentication service. A client can call this routine to learn the default protection level before specifying rpc_c_protect_level_default for the protect_level parameter in the rpc_binding_set_auth_info() routine. If the default level is inappropriate, the client can specify a different, explicit level. A called remote procedure within a server application can call this routine to obtain the default protection level for a given authentication service. By calling routine rpc_binding_inq_auth_client() in the remote procedure, the server can obtain the protection level set up by the calling client. The server can then compare the client-specified protection level with the default level to determine whether to allow the remote procedure to execute. Alternatively, a remote procedure can compare the client's protection level against a level other than the default level. In this case there is no need for the server's remote procedure to call this routine. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_inq_auth_client rpc_binding_set_auth_info 4 rpc_mgmt_inq_if_ids NAME rpc_mgmt_inq_if_ids - Returns a vector of interface identifiers of interfaces a server offers Used by client, server, or management applications. SYNOPSIS #include void rpc_mgmt_inq_if_ids( rpc_binding_handle_t binding, rpc_if_id_vector_t **if_id_vector, unsigned32 *status ); PARAMETERS Input binding Specifies a binding handle. To receive interface identifiers from a remote application, specify a server binding handle for that application. To receive interface information about your own (local) application, specify NULL. If the binding handle you supply refers to partially bound binding information and the binding information contains a nil object UUID, this routine returns the rpc_s_binding_incomplete status code. In this case, the DCE Host Daemon (dced) does not know which serveR instance to select from the local endpoint map because the RPC management interface is automatically registered (by the RPC runtime) for all RPC servers. To avoid this situation, you can obtain a fully bound server binding handle by calling the rpc_ep_resolve_binding() routine. Output if_id_vector Returns the address of an interface identifier vector. status Returns the status code from this routine, which indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_binding_incomplete Binding incomplete (no object ID and no endpoint). rpc_s_comm_failure Communications failure. rpc_s_invalid_arg Invalid argument. rpc_s_invalid_binding Invalid binding handle. rpc_s_mgmt_op_disallowed Management operation disallowed. rpc_s_no_interfaces No interfaces registered. rpc_s_wrong_kind_of_binding Wrong kind of binding for operation. In addition to the values above, status can return the value of parameter status from the application-defined authorization function (rpc_mgmt_authorization_fn_t). The prototype for such a function is defined in the authorization_fn parameter listed in the reference page for the rpc_mgmt_set_authorization_fn routine. DESCRIPTION An application calls the rpc_mgmt_inq_if_ids() routine to obtain a vector of interface identifiers listing the interfaces registered by a server with the RPC runtime. If a server has not registered any interfaces with the runtime, this routine returns a rpc_s_no_interfaces status code and an if_id_vector parameter value of NULL. The application calls the rpc_if_id_vector_free() routine to release the memory used by the vector. By default, the RPC runtime allows all clients to remotely call this routine. To restrict remote calls of this routine, a server application supplies an authorization function using the rpc_mgmt_set_authorization_fn() routine. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ep_resolve_binding rpc_if_id_vector_free rpc_mgmt_set_authorization_fn rpc_server_register_if 4 rpc_mgmt_inq_server_princ_name NAME rpc_mgmt_inq_server_princ_name - Returns a server's principal name Used by client, server, or management applications. SYNOPSIS #include void rpc_mgmt_inq_server_princ_name( rpc_binding_handle_t binding, unsigned32 authn_svc, unsigned_char_t **server_princ_name, unsigned32 *status ); PARAMETERS Input binding Specifies a binding handle. If a client application wants the princi pal name from a server application, supply a server binding handle for that server. For a server application to receive a principal name of itself, supply the value NULL. If the binding handle you supply refers to partially bound binding information and the binding information contains a nil object UUID, this routine returns the rpc_s_binding_incomplete status code. In this case the DCE Host Daemon does not know which server instance to select from the local endpoint map because the RPC runtime automatically registers the RPC management interface for all RPC servers. You can avoid this situation by calling rpc_ep_resolve_binding() to obtain a fully bound server binding handle. authn_svc Specifies the authentication service for which a principal name is returned. The rpc_binding_set_auth_info reference page, in its explanation of the authn_svc parameter, contains a list of supported authentication services. Output server_princ_name Returns a principal name. This name is registered for the authentication service in parameter authn_svc by the server referenced in parameter binding. If the server registered multiple principal names, only one of them is returned. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_binding_incomplete Binding incomplete (no object ID and no endpoint). rpc_s_comm_failure Communications failure. rpc_s_mgmt_op_disallowed Management operation disallowed. rpc_s_unknown_authn_service Unknown authentication service. rpc_s_wrong_kind_of_binding Wrong kind of binding for operation. In addition to the above values, status can return the value of parameter status from the application-defined authorization function (rpc_mgmt_authorization_fn_t). The prototype for such a function is defined in the authorization_fn parameter in the reference page for rpc_mgmt_set_authorization_fn. DESCRIPTION An application calls the rpc_mgmt_inq_server_princ_name() routine to obtain the principal name of a server registered for a specified authentication service. A client (or management) application uses this routine when it wants to allow one-way authentication with the server specified by binding. This means that the client does not care which server principal receives the remote procedure call request. However, the server verifies that the client is who the client claims to be. For one-way authentication, a client calls this routine before calling rpc_binding_set_auth_info(). A server application uses this routine to obtain the principal name it registered by calling rpc_server_register_auth_info(). The RPC runtime allocates memory for the string returned in server_princ_name. The application calls rpc_string_free() to deallocate that memory. By default, the RPC runtime allows all clients to call this routine remotely. To restrict these calls, a server application supplies an authorization function by calling rpc_mgmt_set_authorization_fn(). RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_inq_object rpc_binding_set_auth_info rpc_ep_resolve_binding rpc_mgmt_set_authorization_fn rpc_server_register_auth_info rpc_string_free uuid_is_nil 4 rpc_mgmt_inq_stats NAME rpc_mgmt_inq_stats - Returns RPC runtime statistics Used by client, server, or management applications. SYNOPSIS #include void rpc_mgmt_inq_stats( rpc_binding_handle_t binding, rpc_stats_vector_t **statistics, unsigned32 *status ); PARAMETERS Input binding Specifies a binding handle. To receive statistics about a remote application, specify a server binding handle for that application. To receive statistics about your own (local) application, specify NULL. If the binding handle you supply refers to partially bound binding information and the binding information contains a nil object UUID, this routine returns the rpc_s_binding_incomplete status code. In this case, the DCE Host Daemon does not know which server instance to select from the local endpoint map because the RPC management interface is automatically registered (by the RPC runtime) for all RPC servers. To avoid this situation, you can obtain a fully bound server binding handle by calling the rpc_ep_resolve_binding() routine. Output statistics Returns the statistics vector for the server specified by the binding parameter. Each statistic is a value of the type unsigned32. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_binding_incomplete Binding incomplete (no object ID and no endpoint). rpc_s_comm_failure Communications failure. rpc_s_invalid_binding Invalid binding handle. rpc_s_mgmt_op_disallowed Management operation disallowed. rpc_s_wrong_kind_of_binding Wrong kind of binding for operation. In addition to the above values, status can return the value of parameter status from the application-defined authorization function rpc_mgmt_authorization_fn_t(). The prototype for such a function is defined in the authorization_fn parameter in the reference page for rpc_mgmt_set_authorization_fn. DESCRIPTION The rpc_mgmt_inq_stats() routine returns statistics from the RPC runtime about a specified server. The explanation of a statistics vector in the rpc_intro reference page lists the elements of the vector. The RPC runtime allocates memory for the statistics vector. The application calls the rpc_mgmt_stats_vector_free() routine to release the memory that the statistics vector used. By default, the RPC runtime allows all clients to remotely call this routine. To restrict remote calls of this routine, a server application supplies an authorization function using the rpc_mgmt_set_authorization_fn() routine. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ep_resolve_binding rpc_mgmt_set_authorization_fn rpc_mgmt_stats_vector_free 4 rpc_mgmt_is_server_listening NAME rpc_mgmt_is_server_listening - Tells whether a server is listening for remote procedure calls Used by client, server, or management applications. SYNOPSIS #include boolean32 rpc_mgmt_is_server_listening( rpc_binding_handle_t binding, unsigned32 *status ); PARAMETERS Input binding Specifies a server binding handle. To determine if a remote application is listening for remote procedure calls, specify a server binding handle for that application. To determine if your own (local) application is listening for remote procedure calls, specify NULL. If the binding handle you supply refers to partially bound binding information and the binding information contains a nil object UUID,this routine returns the rpc_s_binding_incomplete status code. In this case, the DCE Host Daemon does not know which server instance to select from the local endpoint map because the RPC management interface is automatically registered (by the RPC runtime) for all RPC servers. To avoid this situation, you can obtain a fully bound server binding handle by calling the rpc_ep_resolve_binding() routine. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_binding_incomplete Binding incomplete (no object ID and no endpoint). rpc_s_comm_failure Communications failure. rpc_s_invalid_binding Invalid binding handle. rpc_s_mgmt_op_disallowed Management operation disallowed. rpc_s_wrong_kind_of_binding Wrong kind of binding for operation. In addition to the above values, status can return the value of parameter status from the application-defined authorization function (rpc_mgmt_authorization_fn_t). The prototype for such a function is defined in the authorization_fn parameter in the reference page for rpc_mgmt_set_authorization_fn. DESCRIPTION The rpc_mgmt_is_server_listening() routine determines whether the server specified in the binding parameter is listening for remote procedure calls. This routine returns a value of TRUE if the server is blocked in the rpc_server_listen() routine. By default, the RPC runtime allows all clients to remotely call this routine. To restrict remote calls of this routine, a server application supplies an authorization function using the rpc_mgmt_set_authorization_fn() routine. RETURN VALUES Your program must examine the return value of the status parameter and the return value of the routine to understand the meaning of the routine value. The following table summarizes the values that this routine can return. Values Returned by rpc_mgmt_is_server_listening() _____________________________________________________________________ Value Returned Status Code Explanation _____________________________________________________________________ TRUE rpc_s_ok The specified server is listening for remote procedure calls. FALSE One of the status The specified server is codes listed for not listening for remote the status parameter procedure calls, or the server cannot be reached. RELATED INFORMATION Functions: rpc_ep_resolve_binding rpc_mgmt_set_authorization_fn rpc_server_listen 4 rpc_mgmt_set_authorization_fn NAME rpc_mgmt_set_authorization_fn - Establishes an authorization function for processing remote calls to a server's management routines Used by server applications. SYNOPSIS #include void rpc_mgmt_set_authorization_fn( rpc_mgmt_authorization_fn_t authorization_fn, unsigned32 *status ); PARAMETERS Input authorization_fn Specifies a pointer to an authorization function. The RPC server runtime automatically calls this function whenever the server runtime receives a client request to execute one of the RPC management routines. Specify NULL to unregister a previously registered authorization function. In this case, the default authorizations (as described later) are used. The following C definition for rpc_mgmt_authorization_fn_t illustrates the prototype for the authorization function: typedef boolean32 (*rpc_mgmt_authorization_fn_t) ( rpc_binding_handle_t client_binding, /* in */ unsigned32 requested_mgmt_operation, /* in */ unsigned32 *status /* out */ ); The following table shows the requested_mgmt_operation Values passed by the RPC runtime to the authorization function. Operation Values Passed to Authorization Function _________________________________________________________________ Called Remote Routine requested_mgmt_operation Value _________________________________________________________________ rpc_mgmt_inq_if_ids() rpc_c_mgmt_inq_if_ids rpc_mgmt_inq_server_princ_name() rpc_c_mgmt_inq_princ_name rpc_mgmt_inq_stats() rpc_c_mgmt_inq_stats rpc_mgmt_is_server_listening() rpc_c_mgmt_is_server_listen rpc_mgmt_stop_server_listening() rpc_c_mgmt_stop_server_listen Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status code and its meaning is as follows: rpc_s_ok Success. DESCRIPTION The rpc_mgmt_set_authorization_fn() routine sets up an authorization function to control remote access to the calling server's remote management routines. If a server does not provide an authorization function, the RPC runtime controls client application access to the server's remote management routines as shown in the next table. In the table, an Enabled authorization allows all clients to execute the remote routine and a Disabled authorization prevents all clients from executing the remote routine. Default Controls for Remote Management Routines ________________________________________________________ Remote Routine Default Authorization ________________________________________________________ rpc_mgmt_inq_if_ids() Enabled rpc_mgmt_inq_server_princ_name() Enabled rpc_mgmt_inq_stats() Enabled rpc_mgmt_is_server_listening() Enabled rpc_mgmt_stop_server_listening() Disabled A server can modify the default authorizations by calling rpc_mgmt_set_authorization_fn() to specify an authorization function. When an authorization function is provided, the RPC runtime automatically calls that function to control the execution of all remote management routines called by clients. The specified function must provide access control for all of the remote management routines. If the authorization function returns TRUE, the management routine is allowed to execute. If the authorization function returns FALSE, the management routine does not execute, and the called routine returns to the client the status code returned from the rpc_mgmt_authorization_fn_t function. However, if the status code that the rpc_mgmt_authorization_fn_t function returns is 0 (zero) or rpc_s_ok, then the status code rpc_s_mgmt_op_disallowed is returned to the client. The RPC runtime calls the server-provided authorization function with the following two input arguments: + The binding handle of the calling client. + An integer value denoting which management routine the client has called. Using these arguments, the authorization function determines whether the calling client is allowed to execute the requested management routine. For example, the authorization function can call rpc_binding_inq_auth_client() to obtain authentication and authorization information about the calling client and determine if that client is authorized to execute the requested management routine. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_mgmt_ep_unregister rpc_mgmt_inq_if_ids rpc_mgmt_inq_server_princ_name rpc_mgmt_inq_stats rpc_mgmt_is_server_listening rpc_mgmt_stop_server_listening 4 rpc_mgmt_set_cancel_timeout NAME rpc_mgmt_set_cancel_timeout - Sets the lower bound on the time to wait before timing out after forwarding a cancel Used by client applications. SYNOPSIS #include void rpc_mgmt_set_cancel_timeout( signed32 seconds, unsigned32 *status ); PARAMETERS Input seconds An integer specifying the number of seconds to wait for a server to acknowledge a cancel. To specify that a client waits an infinite amount of time, supply the value rpc_c_cancel_infinite_timeout. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status code and its meaning is as follows: rpc_s_ok Success. DESCRIPTION The rpc_mgmt_set_cancel_timeout() routine resets the amount of time the RPC runtime waits for a server to acknowledge a cancel before orphaning the call. The application specifies either to wait forever or to wait a length of time specified in seconds. If the value of seconds is 0 (zero), the remote procedure call is immediately orphaned when the RPC runtime detects and forwards a pending cancel; control returns immediately to the client application. The default value, rpc_c_cancel_infinite_timeout, specifies waiting forever for the call to complete. The value for the cancel time-out applies to all remote procedure calls made in the current thread. A multithreaded client that wishes to change the time-out value must call this routine in each thread of execution. For more information about canceled threads and orphaned remote procedure calls, see the OSF DCE Application Development Guide. RETURN VALUES No value is returned. RELATED INFORMATION Functions: pthread_cancel pthread_setcancel Books: OSF DCE Application Development Guide. 4 rpc_mgmt_set_com_timeout NAME rpc_mgmt_set_com_timeout - Sets the communications time-out value in a binding handle Used by client applications. SYNOPSIS #include void rpc_mgmt_set_com_timeout( rpc_binding_handle_t binding, unsigned32 timeout, unsigned32 *status ); PARAMETERS Input binding Specifies the server binding handle whose time-out value is set. timeout Specifies a communications time-out value. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_invalid_binding Invalid binding handle. rpc_s_invalid_timeout Invalid time-out value. rpc_s_wrong_kind_of_binding Wrong kind of binding for operation. DESCRIPTION The rpc_mgmt_set_com_timeout() routine resets the communications time-out value in a server binding handle. The time-out value specifies the relative amount of time to spend trying to communicate with the server. Depending on the protocol sequence for the specified binding handle, the timeout value acts only as advice to the RPC runtime. After the initial relationship is established, subsequent communications for the binding handle can revert to not less than the default time-outs for the protocol service. This means that after setting a short initial time-out, establishing a connection, calls in progress are not timed out any sooner than the default. The time-out value can be any integer value from 0 (zero) to 10. Note that these values do not represent seconds. They represent a relative amount of time to spend to establish a client/server relationship (a binding). Constants are provided for certain values in the time-out range. The following table lists the binding time-out values, describing the DCE RPC predefined values that an application can use for the timeout parameter. Predefined Time-Out Values _____________________________________________________________________ Name Value Description _____________________________________________________________________ rpc_c_binding_min_timeout 0 Attempts to communicate for the minimum amount of time for the network protocol being used. This value favors response time over correctness in determining whether the server is running. rpc_c_binding_default_timeout 5 Attempts to communicate for an average amount of time for the network protocol being used. This value gives equal con- sideration to response time and correctness in determining whether a server is running. This is the default value. rpc_c_binding_max_timeout 9 Attempts to communicate for the longest finite amount of time for the network protocol being used. This value favors correctness in determining whether a server is running over response time. rpc_c_binding_infinite_timeout 10 Attempts to communicate forever. Note that connection-oriented RPC handles the time-out value differently from Datagram RPC. Because connection-oriented RPC is based upon a reliable transport layer, communications time-outs are not as significant as they are under datagram protocol. When rpc_mgmt_set_com_timeout() is called on a binding using connection- oriented protocol, only the input argument rpc_c_binding_infinite_timeout changes the binding's behavior. All other values are ignored. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_mgmt_inq_com_timeout 4 rpc_mgmt_set_server_stack_size NAME rpc_mgmt_set_server_stack_size - Specifies the stack size for each server thread Used by server applications. SYNOPSIS #include void rpc_mgmt_set_server_stack_size( unsigned32 thread_stack_size, unsigned32 *status ); PARAMETERS Input thread_stack_size Specifies, in bytes, the stack size allocated for each thread created by rpc_server_listen(). This value is applied to all threads created for the server. Select this value based on the stack requirements of the remote procedures offered by the server. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_invalid_arg Invalid argument. rpc_s_not_supported Not supported. DESCRIPTION The rpc_mgmt_set_server_stack_size() routine specifies the thread stack size to use when the RPC runtime creates call threads for executing remote procedure calls. The max_calls_exec parameter in rpc_server_listen() specifies the number of call execution threads created. A server, provided it knows the stack requirements of all the manager routines in the interfaces it offers, can call rpc_mgmt_set_server_stack_size() to ensure that each call thread has the necessary stack size. This routine is optional. When it is used, it must be called before the server calls rpc_server_listen(). If a server does not call this routine, the default per thread stack size from the underlying threads package is used. Some thread packages do not support the specification or modification of thread stack sizes. The packages cannot perform such operations or the concept of a thread stack size is meaningless to them. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_server_listen 4 rpc_mgmt_stats_vector_free NAME rpc_mgmt_stats_vector_free - Frees a statistics vector Used by client, server, or management applications. SYNOPSIS #include void rpc_mgmt_stats_vector_free( rpc_stats_vector_t **stats_vector, unsigned32 *status ); PARAMETERS Input/Output stats_vector Specifies the address of a pointer to a statistics vector. On return, stats_vector contains the value NULL. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status code and its meaning is as follows: rpc_s_ok Success. DESCRIPTION An application calls rpc_mgmt_stats_vector_free() to release the memory used to store a vector of statistics. An application calls rpc_mgmt_inq_stats() to obtain a vector of statistics. Follow a call to rpc_mgmt_inq_stats() with a call to rpc_mgmt_stats_vector_free(). RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_mgmt_inq_stats 4 rpc_mgmt_stop_server_listening NAME rpc_mgmt_stop_server_listening - Tells a server to stop listening for remote procedure calls Used by client, server, or management applications. SYNOPSIS #include ( void rpc_mgmt_stop_server_listening( rpc_binding_handle_t binding, unsigned32 *status ); PARAMETERS Input binding Specifies a server binding handle. To direct a remote server to stop listening for remote procedure calls, specify a server binding handle to that server. To direct your own (local) server to stop listening for remote procedure calls, specify NULL. If the binding handle you supply refers to partially bound binding information and the binding information contains a nil object UUID, this routine returns the rpc_s_binding_incomplete status code. In this case, the DCE Host Daemon does not know which server instance to select from the local endpoint map because the RPC management interface is automatically registered (by the RPC runtime) for all RPC servers. To avoid this situation, you can obtain a fully bound server binding handle by calling rpc_ep_resolve_binding(). Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_binding_incomplete Binding incomplete (no object ID and no endpoint). rpc_s_comm_failure Communications failure. rpc_s_invalid_binding Invalid binding handle. rpc_s_mgmt_op_disallowed Management operation disallowed. rpc_s_unknown_if Unknown interface. rpc_s_wrong_kind_of_binding Wrong kind of binding for operation. In addition to the above values, status can return the value of parameter status from the application-defined authorization function rpc_mgmt_authorization_fn_t(). The prototype for such a function is defined in the authorization_fn parameter in the reference page for rpc_mgmt_set_authorization_fn. DESCRIPTION The rpc_mgmt_stop_server_listening() routine directs a server to stop listening for remote procedure calls. On receiving such a request, the DCE RPC runtime stops accepting new remote procedure calls. Executing calls are allowed to complete. After all calls complete, rpc_server_listen() returns to the caller. By default, the RPC runtime does not allow any client to remotely call this routine. To allow clients to execute this routine, a server application supplies an authorization function using rpc_mgmt_set_authorization_fn(). RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ep_resolve_binding rpc_mgmt_set_authorization_fn rpc_server_listen 4 rpc_network_inq_protseqs NAME rpc_network_inq_protseqs - Returns all protocol sequences supported by both the RPC runtime and the operating system Used by client and server applications. SYNOPSIS #include ( void rpc_network_inq_protseqs( rpc_protseq_vector_t **protseq_vector, unsigned32 *status ); PARAMETERS Input None. Output protseq_vector Returns the address of a protocol sequence vector. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_no_protseqs No supported protocol sequences. DESCRIPTION The rpc_network_inq_protseqs() routine obtains a vector containing the protocol sequences supported by the RPC runtime and the operating system. A server chooses to accept remote procedure calls over some or all of the supported protocol sequences. If there are no supported protocol sequences, this routine returns the rpc_s_no_protseqs status code and the value NULL in the protseq_vector parameter. The application calls rpc_protseq_vector_free() to release the memory used by the vector. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_network_is_protseq_valid rpc_protseq_vector_free 4 rpc_network_is_protseq_valid NAME rpc_network_is_protseq_valid - Tells whether the specified protocol sequence is supported by both the RPC runtime and the operating system Used by client and server applications. SYNOPSIS #include ( boolean32 rpc_network_is_protseq_valid( unsigned_char_t *protseq, unsigned32 *status ); PARAMETERS Input protseq Specifies a string identifier for a protocol sequence. (See the table of valid protocol sequences in the rpc_intro reference page for a list of acceptable values.) The rpc_network_is_protseq_valid() routine determines whether this parameter contains a valid protocol sequence. If not, the routine returns FALSE and the status parameter contains the rpc_s_invalid_rpc_protseq status code. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_invalid_rpc_protseq Invalid protocol sequence. rpc_s_protseq_not_supported Protocol sequence not supported on this host. DESCRIPTION The rpc_network_is_protseq_valid() routine determines whether a specified protocol sequence is available for making remote procedure calls. A server chooses to accept remote procedure calls over some or all of the supported protocol sequences. A protocol sequence is valid if the RPC runtime and the operating system support the protocol sequence. DCE RPC supports the protocol sequences pointed to by the explanation of the protseq parameter. An application calls rpc_network_inq_protseqs() to obtain all the supported protocol sequences. RETURN VALUES This routine can return the following values: TRUE The RPC runtime supports the protocol sequence specified in the protseq parameter. The routine returns the status code rpc_s_ok in the status parameter. FALSE The RPC runtime does not support the protocol sequence specified in the protseq parameter. RELATED INFORMATION Functions: rpc_network_inq_protseqs rpc_string_binding_parse 4 rpc_ns_binding_export NAME rpc_ns_binding_export - Establishes a name service database entry with binding handles or object UUIDs for a server Used by server applications. SYNOPSIS #include ( void rpc_ns_binding_export( unsigned32 entry_name_syntax, unsigned_char_t *entry_name, rpc_if_handle_t if_handle, rpc_binding_vector_t *binding_vec, uuid_vector_t *object_uuid_vec, unsigned32 *status ); PARAMETERS Input entry_name_syntax An integer value that specifies the syntax of the entry_name parameter. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide the value rpc_c_ns_syntax_default. entry_name Specifies the entry name to which binding handles and object UUIDs are exported. This can be either the global or cell-relative name. if_handle Specifies a stub-generated data structure that identifies the interface to export. Specifying the value NULL indicates there are no binding handles to export (only object UUIDs are exported) and the binding_vec parameter is ignored. binding_vec Specifies a vector of server bindings to export. Specify the value NULL for this parameter in cases where there are no binding handles to export (only object UUIDs are exported). object_uuid_vec Identifies a vector of object UUIDs offered by the server. The server application constructs this vector. NULL indicates there are no object UUIDs to export (only binding handles are exported). Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_incomplete_name Incomplete name. rpc_s_invalid_binding Invalid binding handle. rpc_s_invalid_name_syntax Invalid name syntax. rpc_s_name_service_unavailable Name service unavailable. rpc_s_no_ns_permission No permission for name service operation. rpc_s_nothing_to_export Nothing to export. rpc_s_unsupported_name_syntax Unsupported name syntax. rpc_s_wrong_kind_of_binding Wrong kind of binding for operation. DESCRIPTION The rpc_ns_binding_export() routine allows a server application to publicly offer, in the name service database, an interface that any client application can use. A server application can also use this routine to publicly offer the object UUIDs of the application's resources. To export an interface, the server application calls the routine with an interface and the server binding handles that a client can use to access the server. A server can export interfaces and objects in a single call to this routine, or it can export them separately. If the entry in the name service database specified by the entry_name parameter does not exist, rpc_ns_binding_export() tries to create it. In this case a server must have the correct permissions to create the entry. Otherwise, a management application with the necessary permissions creates the entry by calling rpc_ns_mgmt_entry_create() before the server runs. A server is not required to export its interfaces to the name service database. When a server does not export any interfaces, only clients that privately know of that server's binding information can access its interfaces. For example, a client that has the information needed to construct a string binding can call rpc_binding_from_string_binding() to create a binding handle for making remote procedure calls to a server. Before calling rpc_ns_binding_export() to export interfaces (but not to export object UUIDs), a server must do the following: + Register one or more protocol sequences with the local RPC runtime by calling one of the following routines: rpc_server_use_protseq() rpc_server_use_protseq_ep() rpc_server_use_protseq_if() rpc_server_use_all_protseqs() rpc_server_use_all_protseqs_if() + Obtain a list of server bindings by calling rpc_server_inq_bindings(). The vector returned from rpc_server_inq_bindings() becomes the binding_vec parameter for this routine. To prevent a binding from being exported, set the selected vector element to the value NULL. (See the section on RPC data types and structures in the rpc_intro reference page.) If a server exports an interface to the same entry in the name service database more than once, the second and subsequent calls to this routine add the binding information and object UUIDs only if they differ from the ones in the server entry. Existing data is not removed from the entry. To remove binding handles and object UUIDs from the name service database, a server application calls rpc_ns_binding_unexport() and a management application calls rpc_ns_mgmt_binding_unexport(). For an explanation of how a server can establish a client/server relationship without using the name service database, see the explanation of a string binding in the rpc_intro reference page. In addition to calling this routine, a server that called either rpc_server_use_all_protseqs() or rpc_server_use_protseq() must also register with the local endpoint map by calling rpc_ep_register() or rpc_ep_register_no_replace(). Permissions Required You need both read permission and write permission to the CDS object entry (the target name service entry). If the entry does not exist, you also need insert permission to the parent directory. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ep_register rpc_ep_register_no_replace rpc_ns_binding_unexport rpc_ns_mgmt_binding_unexport rpc_ns_mgmt_entry_create rpc_server_inq_bindings rpc_server_use_all_protseqs rpc_server_use_all_protseqs_if rpc_server_use_protseq rpc_server_use_protseq_ep rpc_server_use_protseq_if 4 rpc_ns_binding_import_begin NAME rpc_ns_binding_import_begin - Creates an import context for an interface and an object in the name service database Used by client applications. SYNOPSIS #include ( void rpc_ns_binding_import_begin( unsigned32 entry_name_syntax, unsigned_char_t *entry_name, rpc_if_handle_t if_handle, uuid_t *obj_uuid, rpc_ns_handle_t *import_context, unsigned32 *status ); PARAMETERS Input entry_name_syntax An integer value that specifies the syntax of parameter entry_name. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide the value rpc_c_ns_syntax_default. entry_name Specifies the entry name where the search for compatible binding handles begins. This can be either the global or cell-relative name. To use the entry name found in the RPC_DEFAULT_ENTRY logical name, supply NULL or a null string (\0) for this parameter. When this entry name is used, the RPC runtime automatically uses the default name syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name. if_handle A stub-generated data structure specifying the interface to import. If the interface specification has not been exported or is of no concern to the caller, specify NULL for this parameter. In this case the bindings returned are only guaranteed to be of a compatible and supported protocol sequence and, depending on the value of parameter obj_uuid, contain the specified object UUID.The desired interface may not be supported by the contacted server. obj_uuid Specifies an optional object UUID. If you specify NULL or a nil UUID for this parameter, the returned binding handles contain one of the object UUIDs that the compatible server exported. If the server did not export any object UUIDs, the returned compatible binding handles contain a nil object UUID. If you specify a non-nil UUID, compatible binding handles are returned from an entry only if the server has exported the specified object UUID. Each returned binding handle contains the specified non-nil object UUID. Output import_context Returns the name service handle for use with the rpc_ns_binding_import_next() and rpc_ns_binding_import_done() routines. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_incomplete_name Incomplete name. rpc_s_invalid_name_syntax Invalid name syntax. rpc_s_invalid_object Invalid object. rpc_s_no_env_setup Environment variable not set up. rpc_s_unsupported_name_syntax Unsupported name syntax. DESCRIPTION The rpc_ns_binding_import_begin() routine creates an import context for importing compatible server binding handles for servers. These servers offer the specified interface and object UUID in the respective if_handle and obj_uuid parameters. Before calling rpc_ns_binding_import_next(), the client must first call this routine to create an import context. The arguments to this routine control the operation of rpc_ns_binding_import_next(). After importing binding handles, the client calls rpc_ns_binding_import_done() to delete the import context. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_binding_import_done rpc_ns_binding_import_next rpc_ns_mgmt_handle_set_exp_age 4 rpc_ns_binding_import_done NAME rpc_ns_binding_import_done - Deletes the import context for searching the name service database Used by client applications. SYNOPSIS #include void rpc_ns_binding_import_done( rpc_ns_handle_t *import_context, unsigned32 *status ); PARAMETERS Input/Output import_context Specifies the name service handle to delete. (A name service handle is created by calling rpc_ns_binding_import_begin().) Returns the value NULL. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_invalid_ns_handle Invalid name service handle. DESCRIPTION The rpc_ns_binding_import_done() routine deletes an import context created by calling rpc_ns_binding_import_begin(). This deletion does not affect any previously imported bindings. Typically, a client calls this routine after completing remote procedure calls to a server using a binding handle returned from rpc_ns_binding_import_next(). A client program calls this routine for each created import context, regardless of the status returned from rpc_ns_binding_import_next(), or the success in making remote procedure calls. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_binding_import_begin rpc_ns_binding_import_next 4 rpc_ns_binding_import_next NAME rpc_ns_binding_import_next - Returns a binding handle of a compatible server (if found) from the name service database Used by client applications. SYNOPSIS #include void rpc_ns_binding_import_next( rpc_ns_handle_t import_context, rpc_binding_handle_t *binding, unsigned32 *status ); PARAMETERS Input import_context Specifies a name service handle. This handle is returned from the rpc_ns_binding_import_begin() routine. Output binding Returns a compatible server binding handle. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_class_version_mismatch RPC class version mismatch. rpc_s_entry_not_found Name service entry not found. rpc_s_invalid_ns_handle Invalid name service handle. rpc_s_name_service_unavailable Name service unavailable. rpc_s_no_more_bindings No more bindings. rpc_s_no_ns_permission No permission for name service operation. rpc_s_not_rpc_entry Not an RPC entry. DESCRIPTION The rpc_ns_binding_import_next() routine returns one compatible (to the client) server binding handle selected at random from the name service database. The server offers the interface and object UUID specified by the respective if_handle and obj_uuid parameters in rpc_ns_binding_import_begin(). A similar routine is rpc_ns_binding_lookup_next(), which returns a vector of compatible server binding handles for one or more servers. NOTE: Routine rpc_ns_binding_import_next() calls routine rpc_ns_binding_lookup_next() which, in turn, obtains a vector of server binding handles from the name service database. Next, routine rpc_ns_binding_import_next() randomly selects one of the elements from the vector. The rpc_ns_binding_import_next() routine communicates only with the name service database, not directly with servers. The returned compatible binding handle always contains an object UUID. Its value depends on the value specified in the obj_uuid parameter of the rpc_ns_binding_import_begin() routine, as follows: + If obj_uuid contains a non-nil object UUID, the returned binding handle contains that object UUID. + If obj_uuid contains a nil object UUID or NULL, the object UUID returned in the binding handle depends on how the server exported object UUIDs: - If the server did not export any object UUIDs, the returned binding handle contains a nil object UUID. - If the server exported one object UUID, the returned binding handle contains that object UUID. - If the server exported multiple object UUIDs, the returned binding handle contains one of the object UUIDs, selected in an unspecified way. Applications should not count on multiple calls to rpc_ns_binding_import_next() returning different object UUIDs. In particular, note that each name service entry stores server address information separately from exported object UUIDs. Successive calls to rpc_ns_binding_import_next() using the same import context will return exactly one binding for each compatible server address, not the cross product of all compatible server addresses with all exported UUIDs. Each returned binding will contain one of the exported object UUIDs, but applications should not count on any specific selection mechanism for these object UUIDs The client application can use the returned binding handle to make a remote procedure call to the server. If the client fails to communicate with the server, it can call the rpc_ns_binding_import_next() routine again. Each time the client calls rpc_ns_binding_import_next(), the routine returns another server binding handle. The binding handles returned are unordered. Multiple binding handles can refer to different protocol sequences from the same server. When the search finishes, the routine returns a status code of rpc_s_no_more_bindings and returns the value NULL in binding. A client application calls rpc_ns_binding_inq_entry_name() to obtain the name of the entry in the name service database where the binding handle came from. The rpc_ns_binding_import_next() routine allocates memory for the returned binding parameter. When a client application finishes with the binding handle, it must call rpc_binding_free() to deallocate the memory. Each call to rpc_ns_binding_import_next() requires a corresponding call to rpc_binding_free(). The client calls the rpc_ns_binding_import_done() routine after it has satisfactorily used one or more returned server binding handles. The rpc_ns_binding_import_done() routine deletes the import context. The client also calls rpc_ns_binding_import_done() if the application wants to start a new search for compatible servers (by calling rpc_ns_binding_import_begin()). The order of binding handles returned can be different for each new search. This means that the order in which binding handles are returned to an application can be different each time the application is run. Permissions Required You need read permission to the specified CDS object entry (the starting name service entry) and to any CDS object entry in the resulting search path. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_binding_import_begin rpc_ns_binding_import_done rpc_ns_binding_inq_entry_name rpc_ns_binding_lookup_begin rpc_ns_binding_lookup_done rpc_ns_binding_lookup_next rpc_ns_binding_select 4 rpc_ns_binding_inq_entry_name NAME rpc_ns_binding_inq_entry_name - Returns the name of an entry in the name service database from which the server binding handle came Used by client applications. SYNOPSIS #include void rpc_ns_binding_inq_entry_name( rpc_binding_handle_t binding, unsigned32 entry_name_syntax, unsigned_char_t **entry_name, unsigned32 *status ); PARAMETERS Input binding Specifies a server binding handle whose entry name in the name service database is returned. entry_name_syntax An integer value that specifies the syntax of returned parameter entry_name. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide the value rpc_c_ns_syntax_default. Output entry_name Returns the name of the entry in the name service database in which binding was found. The returned name is a global name. Specify NULL to prevent the routine from returning this parameter. When you specify this value, the client does not need to call rpc_string_free(). status Returns the status code from this routine, which indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_incomplete_name Incomplete name. rpc_s_invalid_binding Invalid binding handle. rpc_s_invalid_name_syntax Invalid name syntax. rpc_s_no_entry_name No entry name for binding. rpc_s_unsupported_name_syntax Unsupported name syntax. rpc_s_wrong_kind_of_binding Wrong kind of binding for operation. DESCRIPTION The rpc_ns_binding_inq_entry_name() routine returns the global name of the entry in the name service database from which a binding handle for a compatible server came. The RPC runtime allocates memory for the string returned in the entry_name parameter. Your application calls rpc_string_free() to deallocate that memory. An entry name is associated only with binding handles returned from the rpc_ns_binding_import_next(), rpc_ns_binding_lookup_next(), and rpc_ns_binding_select() routines. If the binding handle specified in the binding parameter is not returned from an entry in the name service database (for example, the binding handle is created by calling rpc_binding_from_string_binding()), this routine returns the rpc_s_no_entry_name status code. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_from_string_binding rpc_ns_binding_import_next rpc_ns_binding_lookup_next rpc_ns_binding_select rpc_string_free 4 rpc_ns_binding_lookup_begin NAME rpc_ns_binding_lookup_begin - Creates a lookup context for an interface and an object in the name service database Used by client applications. SYNOPSIS #include void rpc_ns_binding_lookup_begin( unsigned32 entry_name_syntax, unsigned_char_t *entry_name, rpc_if_handle_t if_handle, uuid_t *object_uuid, unsigned32 binding_max_count, rpc_ns_handle_t *lookup_context, unsigned32 *status ); PARAMETERS Input entry_name_syntax An integer value that specifies the syntax of the entry_name parameter. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide the value rpc_c_ns_syntax_default. entry_name Specifies the entry name at which the search for compatible binding handles begins. This can be either the global or cell- relative name. To use the entry name found in the RPC_DEFAULT_ENTRY logical name, supply NULL or a null string (\0) for this parameter. When this entry name is used, the RPC runtime automatically uses the default name syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name. if_handle A stub-generated data structure specifying the interface to look up. If the interface specification has not been exported or is of no concern to the caller, specify NULL for this parameter. In this case the bindings returned are only guaranteed to be of a compatible and supported protocol sequence and contain the specified object UUID. The desired interface might not be supported by the contacted server. object_uuid Specifies an optional object UUID. If you specify NULL or a nil UUID for this parameter, the returned binding handles contain one of the object UUIDs exported by the compatible server. If the server did not export any object UUIDs, the returned compatible binding handles contain a nil object UUID. For a non-nil UUID, compatible binding handles are returned from an entry only if the server has exported the specified object UUID.Each returned binding handle contains the specified non-nil object UUID. binding_max_count Sets the maximum number of bindings to return in the binding_vector parameter of rpc_ns_binding_lookup_next(). Specify rpc_c_binding_max_count_default to use the default count. Output lookup_context Returns the name service handle for use with the rpc_ns_binding_lookup_next() and rpc_ns_binding_lookup_done() routines. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_incomplete_name Incomplete name. rpc_s_invalid_name_syntax Invalid name syntax. rpc_s_invalid_object Invalid object. rpc_s_no_env_setup Environment variable not set up. rpc_s_unsupported_name_syntax Unsupported name syntax. DESCRIPTION The rpc_ns_binding_lookup_begin() routine creates a lookup context for locating compatible server binding handles for servers. These servers offer the specified interface and object UUID in the respective if_handle and object_uuid parameters. Before calling rpc_ns_binding_lookup_next(), the client application must first create a lookup context by calling rpc_ns_binding_lookup_begin(). The parameters to this routine control the operation of rpc_ns_binding_lookup_next(). When finished locating binding handles, the client application calls the rpc_ns_binding_lookup_done() routine to delete the lookup context. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_binding_lookup_done rpc_ns_binding_lookup_next rpc_ns_mgmt_handle_set_exp_age 4 rpc_ns_binding_lookup_done NAME rpc_ns_binding_lookup_done - Deletes the lookup context for searching the name service database Used by client applications. SYNOPSIS #include void rpc_ns_binding_lookup_done( rpc_ns_handle_t *lookup_context, unsigned32 *status ); PARAMETERS Input/Output lookup_context Specifies the name service handle to delete. (A name service handle is created by calling rpc_ns_binding_lookup_begin().) Returns the value NULL. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_invalid_ns_handle Invalid name service handle. DESCRIPTION The rpc_ns_binding_lookup_done() routine deletes a lookup context created by calling rpc_ns_binding_lookup_begin(). Typically, a client calls this routine after completing remote procedure calls to a server using a binding handle returned from rpc_ns_binding_lookup_next(). A client program calls this routine for each created lookup context, regardless of the status returned from rpc_ns_binding_lookup_next(), or success in making remote procedure calls. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_binding_lookup_begin rpc_ns_binding_lookup_next 4 rpc_ns_binding_lookup_next NAME rpc_ns_binding_lookup_next - Returns a list of binding handles of one or more compatible servers (if found) from the name service database Used by client applications. SYNOPSIS #include void rpc_ns_binding_lookup_next( rpc_ns_handle_t lookup_context, rpc_binding_vector_t **binding_vec, unsigned32 *status ); PARAMETERS Input lookup_context Specifies a name service handle. This handle is returned from the rpc_ns_binding_lookup_begin() routine. Output binding_vec Returns a vector of compatible server binding handles. status Returns the status code from this routine, which indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_class_version_mismatch RPC class version mismatch. rpc_s_entry_not_found Name service entry not found. rpc_s_invalid_ns_handle Invalid name service handle. rpc_s_name_service_unavailable Name service unavailable. rpc_s_no_more_bindings No more bindings. rpc_s_no_ns_permission No permission for name service operation. rpc_s_not_rpc_entry Not an RPC entry. DESCRIPTION The rpc_ns_binding_lookup_next() routine returns a vector of compatible (to the client) server binding handles. The servers offer the interface and object UUID specified by the respective if_handle and object_uuid parameters in rpc_ns_binding_lookup_begin(). The number of binding handles that rpc_ns_binding_lookup_next() attempts to return is the value of binding_max_count in the rpc_ns_binding_lookup_begin() routine. A similar routine is rpc_ns_binding_import_next(), which returns one compatible server binding handle. The rpc_ns_binding_lookup_next() routine communicates only with the name service database, not directly with servers. This routine traverses entries in the name service database, returning compatible server binding handles from each entry. The routine can return multiple binding handles from each entry. The search operation obeys the following rules for traversing the entries: + At each entry visited, the search operation randomly processes binding information, then group members, then profile members. Profile members with different priorities are returned according to their priorities, highest priority first. + The search operation returns members of a group in random order. + The search operation returns members of a profile with the same priority in random order. If the entry where the search begins (see the entry_name parameter in rpc_ns_binding_lookup_begin()) contains binding handles as well as an RPC group and/or a profile, rpc_ns_binding_lookup_next() returns the binding handles from entry_name before searching the group or profile. This means that rpc_ns_binding_lookup_next() can return a partially full vector before processing the members of the group or profile. Each binding handle in the returned vector always contains an object UUID. Its value depends on the value specified in the object_uuid parameter of rpc_ns_binding_lookup_begin() as follows: + If object_uuid contains a non-nil object UUID, each returned binding handle contains that object UUID. + If object_uuid contains a nil object UUID or NULL, the object UUID returned in each binding handle depends on how the server exported object UUIDS: - If the server did not export any object UUIDs, each returned binding handle contains a nil object UUID. - If the server exported one object UUID, each returned binding handle contains that object UUID. - If the server exported multiple object UUIDs, the returned binding handle contains one of the object UUIDs, selected in an unspecified way. Applications should not count on the binding handles returned from a given entry to contain different object UUIDs. In particular, note that each name service entry stores server address information separately from exported object UUIDs. One or more calls to rpc_ns_binding_lookup_next() will return exactly one binding for each compatible server address, not the cross product of all compatible server addresses with all exported UUIDs. Each returned binding will contain one of the exported object UUIDs, but applications should not count on any specific selection mechanism for these object UUIDs From the returned vector of server binding handles, the client application can employ its own criteria for selecting individual binding handles, or the application can call rpc_ns_binding_select() to select a binding handle. The rpc_binding_to_string_binding() and rpc_string_binding_parse() routines are useful for a client creating its own selection criteria. The client application can use the selected binding handle to attempt a remote procedure call to the server. If the client fails to communicate with the server, it can select another binding handle from the vector. When all the binding handles in the vector are used, the client application calls rpc_ns_binding_lookup_next() again. Each time the client calls rpc_ns_binding_lookup_next(), the routine returns another vector of binding handles. The binding handles returned in each vector are unordered, as is the order in which the vectors are returned from multiple calls to this routine. When looking up compatible binding handles from a profile, the binding handles from entries of equal profile priority are unordered in the returned vector. In addition, the vector returned from a call to rpc_ns_binding_lookup_next() contains only compatible binding handles from entries of equal profile priority. This means the returned vector may be partially full. For example, if the binding_max_count parameter value in rpc_ns_binding_lookup_begin() was 5 and rpc_ns_binding_lookup_next() finds only three compatible binding handles from profile entries of priority 0 (zero), rpc_ns_binding_lookup_next() returns a partially full binding vector (with three binding handles). The next call to rpc_ns_binding_lookup_next() creates a new binding vector and begins looking for compatible binding handles from profile entries of priority 1. When the search finishes, the routine returns a status code of rpc_s_no_more_bindings and returns the value NULL in binding_vec. A client application calls rpc_ns_binding_inq_entry_name() to obtain the name of the entry in the name service database where the binding handle came from. The rpc_ns_binding_lookup_next() routine allocates memory for the returned binding_vec. When a client application finishes with the vector, it must call rpc_binding_vector_free() to deallocate the memory. Each call to rpc_ns_binding_lookup_next() requires a corresponding call to rpc_binding_vector_free(). The client calls rpc_ns_binding_lookup_done(), which deletes the lookup context. The client also calls rpc_ns_binding_lookup_done() if the application wants to start a new search for compatible servers (by calling rpc_ns_binding_lookup_begin()). The order of binding handles returned can be different for each new search. This means that the order in which binding handles are returned to an application can be different each time the application is run. Permissions Required You need read permission to the specified CDS object entry (the starting name service entry) and to any CDS object entry in the resulting search path. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_to_string_binding rpc_binding_vector_free rpc_ns_binding_import_next rpc_ns_binding_inq_entry_name rpc_ns_binding_lookup_begin rpc_ns_binding_lookup_done rpc_ns_binding_select rpc_string_binding_parse 4 rpc_ns_binding_select NAME rpc_ns_binding_select - Returns a binding handle from a list of compatible server binding handles Used by client applications. SYNOPSIS #include void rpc_ns_binding_select( rpc_binding_vector_t *binding_vec, rpc_binding_handle_t *binding, unsigned32 *status ); PARAMETERS Input/Output binding_vec Specifies the vector of compatible server binding handles from which a binding handle is selected. The returned binding vector no longer references the selected binding handle (returned separately in the binding parameter). Output binding Returns a selected server binding handle. status Returns the status code from this routine, which indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_no_more_bindings No more bindings. DESCRIPTION The rpc_ns_binding_select() routine randomly chooses and returns a server binding handle from a vector of server binding handles. Each time the client calls rpc_ns_binding_select(), the routine returns another binding handle from the vector. When all of the binding handles are returned from the vector, the routine returns a status code of rpc_s_no_more_bindings and returns the value NULL in binding. The select operation allocates storage for the data referenced by the returned binding parameter. When a client finishes with the binding handle, it calls rpc_binding_free() to deallocate the storage. Each call to the rpc_ns_binding_select() routine requires a corresponding call to rpc_binding_free(). Instead of using this routine, client applications can select a binding handle according to their specific needs. In this case the rpc_binding_to_string_binding() and rpc_string_binding_parse() routines are useful to the applications since the routines work together to extract the individual fields of a binding handle for examination. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_free rpc_binding_to_string_binding rpc_ns_binding_lookup_next rpc_string_binding_parse 4 rpc_ns_binding_unexport NAME rpc_ns_binding_unexport - Removes the binding handles for an interface, or object UUIDs, from an entry in the name service database Used by server applications. SYNOPSIS #include void rpc_ns_binding_unexport( unsigned32 entry_name_syntax, unsigned_char_t *entry_name, rpc_if_handle_t if_handle, uuid_vector_t *object_uuid_vec, unsigned32 *status ); PARAMETERS Input entry_name_syntax An integer value that specifies the syntax of the entry_name parameter. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide the value rpc_c_ns_syntax_default. entry_name Specifies an entry name whose binding handles or object UUIDs are removed. This can be either the global or cell-relative name. if_handle Specifies an interface specification for the binding handles to be removed from the name service database. The value NULL indicates that no binding handles are removed (only object UUIDs are removed). object_uuid_vec Specifies a vector of object UUIDs to be removed from the name service database. The application constructs this vector. The value NULL indicates that no object UUIDs are removed (only binding handles are removed). Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_class_version_mismatch RPC class version mismatch. rpc_s_entry_not_found Name service entry not found. rpc_s_incomplete_name Incomplete name. rpc_s_interface_not_found Interface not found. rpc_s_invalid_name_syntax Invalid name syntax. rpc_s_invalid_vers_option Invalid version option. rpc_s_name_service_unavailable Name service unavailable. rpc_s_no_ns_permission No permission for name service operation. rpc_s_not_all_objs_unexported Not all objects unexported. rpc_s_nothing_to_unexport Nothing to unexport. rpc_s_not_rpc_entry Not an RPC entry. rpc_s_unsupported_name_syntax Unsupported name syntax. DESCRIPTION The rpc_ns_binding_unexport() routine allows a server application to unexport (that is, remove) one of the following from an entry in the name service database: + All the binding handles for an interface. + One or more object UUIDs for a resource or resources. + Both binding handles and object UUIDs. The rpc_ns_binding_unexport() routine removes only those binding handles that match the interface UUID and the major and minor interface version numbers found in the if_handle parameter. To remove multiple versions of an interface, use rpc_ns_mgmt_binding_unexport(). A server application can remove an interface and objects in a single call to this routine, or it can remove them separately. If rpc_ns_binding_unexport() does not find any binding handles for the specified interface, it returns an rpc_s_interface_not_found status code and does not remove the object UUIDs, if any are specified. If one or more binding handles for the specified interface are found and removed without error, rpc_ns_binding_unexport() removes the specified object UUIDs, if any. If any of the specified object UUIDs are not found, rpc_ns_binding_unexport() returns the status code rpc_s_not_all_objs_unexported. A server application, in addition to calling this routine, also calls rpc_ep_unregister() to unregister any endpoints that the server previously registered with the local endpoint map. Use this routine with caution, only when you expect a server to be unavailable for an extended time; for example, when it is permanently removed from service. Additionally, keep in mind that name service databases are designed to be relatively stable. In replicated name service databases, frequent use of rpc_ns_binding_export() and rpc_ns_binding_unexport() causes the name service to remove and replace the same entry repeatedly, and can cause performance problems. Permissions Required You need both read permission and write permission to the CDS object entry (the target name service entry). RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ep_unregister rpc_ns_binding_export rpc_ns_mgmt_binding_unexport 4 rpc_ns_entry_expand_name NAME rpc_ns_entry_expand_name - Expands the name of a name service entry Used by client, server, or management applications. SYNOPSIS #include void rpc_ns_entry_expand_name( unsigned32 entry_name_syntax, unsigned_char_t *entry_name, unsigned_char_t **expanded_name, unsigned32 *status ); PARAMETERS Input entry_name_syntax An integer value that specifies the syntax of the entry_name parameter. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide a value of rpc_c_ns_syntax_default. entry_name Specifies the entry name to expand. This can be either the global or cell-relative name. Output expanded_name Returns a pointer to the expanded version of entry_name. Do not specify NULL since the routine always returns a name string. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_incomplete_name Incomplete name. DESCRIPTION An application calls rpc_ns_entry_expand_name() to obtain a fully expanded entry name. The RPC runtime allocates memory for the returned expanded_name parameter. The application is responsible for calling rpc_string_free() for that returned parameter string. The returned and expanded entry name accounts for local name translations and differences in locally defined naming schemas. For example, suppose the entry in the name service is /.:/subsys/PrintQ/server1 Upon return from rpc_ns_entry_expand_name(),the expanded name could be /.../abc.com/subsys/PrintQ/server1 For more information about local names and their expansions, see the information on the DCE Directory Service in the OSF DCE Administration Guide. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_string_free Books: OSF DCE Administration Guide. 4 rpc_ns_entry_object_inq_begin NAME rpc_ns_entry_object_inq_begin - Creates an inquiry context for viewing the objects of an entry in the name service database Used by client, server, or management applications. SYNOPSIS #include void rpc_ns_entry_object_inq_begin( unsigned32 entry_name_syntax, unsigned_char_t *entry_name, rpc_ns_handle_t *inquiry_context, unsigned32 *status ); PARAMETERS Input entry_name_syntax An integer value that specifies the syntax of the entry_name parameter. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide a value of rpc_c_ns_syntax_default. entry_name Specifies the entry in the name service database for which object UUIDs are viewed. This can be either the global or cell-relative name. Output inquiry_context Returns a name service handle for use with the rpc_ns_entry_object_inq_next() routine, and with the rpc_ns_entry_object_inq_done() routine. status Returns the status code from this routine, indicating whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_incomplete_name Incomplete name. rpc_s_invalid_name_syntax Invalid name syntax. rpc_s_unsupported_name_syntax Unsupported name syntax. DESCRIPTION The rpc_ns_entry_object_inq_begin() routine creates an inquiry context for viewing the object UUIDs exported to entry_name. Before calling rpc_ns_entry_object_inq_next(), the application must first call this routine to create an inquiry context. When finished viewing the object UUIDs, the application calls the rpc_ns_entry_object_inq_done() routine to delete the inquiry context. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_binding_export rpc_ns_entry_object_inq_done rpc_ns_entry_object_inq_next rpc_ns_mgmt_handle_set_exp_age 4 rpc_ns_entry_object_inq_done NAME rpc_ns_entry_object_inq_done - Deletes the inquiry context for viewing the objects of an entry in the name service database Used by client, server, or management applications. SYNOPSIS #include void rpc_ns_entry_object_inq_done( rpc_ns_handle_t *inquiry_context, unsigned32 *status ); PARAMETERS Input/Output inquiry_context Specifies the name service handle to delete. (A name service handle is created by calling rpc_ns_entry_object_inq_begin().) Returns the value NULL. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_invalid_ns_handle Invalid name service handle. DESCRIPTION The rpc_ns_entry_object_inq_done() routine deletes an inquiry context created by calling rpc_ns_entry_object_inq_begin(). An application calls this routine after viewing exported object UUIDs using the rpc_ns_entry_object_inq_next() routine. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_entry_object_inq_begin rpc_ns_entry_object_inq_next 4 rpc_ns_entry_object_inq_next NAME rpc_ns_entry_object_inq_next - Returns one object at a time from an entry in the name service database Used by client, server, or management applications. SYNOPSIS #include void rpc_ns_entry_object_inq_next( rpc_ns_handle_t inquiry_context, uuid_t *obj_uuid, unsigned32 *status ); PARAMETERS Input inquiry_context Specifies a name service handle. This handle is returned from the rpc_ns_entry_object_inq_begin() routine. Output obj_uuid Returns an exported object UUID. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_class_version_mismatch RPC class version mismatch. rpc_s_entry_not_found Name service entry not found. rpc_s_incomplete_name Incomplete name. rpc_s_invalid_ns_handle Invalid name service handle. rpc_s_name_service_unavailable Name service unavailable. rpc_s_no_more_members No more members. rpc_s_no_ns_permission No permission for name service operation. rpc_s_not_rpc_entry Not an RPC entry. DESCRIPTION The rpc_ns_entry_object_inq_next() routine returns one of the object UUIDs exported to an entry in the name service database. The entry_name parameter in the rpc_ns_entry_object_inq_begin() routine specified the entry. An application can view all of the exported object UUIDs by repeatedly calling the rpc_ns_entry_object_inq_next() routine. When all the object UUIDs are viewed, this routine returns an rpc_s_no_more_members status. The returned object UUIDs are unordered. The application supplies the memory for the object UUID returned in the obj_uuid parameter. After viewing the object UUIDs, the application must call the rpc_ns_entry_object_inq_done() routine to delete the inquiry context. The order in which rpc_ns_entry_object_inq_next() returns object UUIDs can be different for each viewing of an entry. Therefore, the order in which an application receives object UUIDs can be different each time the application is run. Permissions Required You need read permission to the CDS object entry (the target name service entry). RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_binding_export rpc_ns_entry_object_inq_begin rpc_ns_entry_object_inq_done 4 rpc_ns_group_delete NAME rpc_ns_group_delete - Deletes a group attribute Used by client, server, or management applications. SYNOPSIS #include void rpc_ns_group_delete( unsigned32 group_name_syntax, unsigned_char_t *group_name, unsigned32 *status ); PARAMETERS Input group_name_syntax An integer value that specifies the syntax of the group_name parameter. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide the integer value rpc_c_ns_syntax_default. group_name Specifies the RPC group to delete. This can be either the global or cell-relative name. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_entry_not_found Name service entry not found. rpc_s_incomplete_name Incomplete name. rpc_s_invalid_name_syntax Invalid name syntax. rpc_s_name_service_unavailable Name service unavailable. rpc_s_no_ns_permission No permission for name service operation. rpc_s_unsupported_name_syntax Unsupported name syntax. DESCRIPTION The rpc_ns_group_delete() routine deletes the group attribute from the specified entry in the name service database. Neither the specified entry nor the entries represented by the group members are deleted. Permissions Required You need write permission to the CDS object entry (the target group entry). RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_group_member_add rpc_ns_group_member_delete 4 rpc_ns_group_mbr_add NAME rpc_ns_group_mbr_add - Adds an entry name to a group; if necessary, creates the entry Used by client, server, or management applications. SYNOPSIS #include void rpc_ns_group_mbr_add( unsigned32 group_name_syntax, unsigned_char_t *group_name, unsigned32 member_name_syntax, unsigned_char_t *member_name, unsigned32 *status ); PARAMETERS Input group_name_syntax An integer value that specifies the syntax of the group_name parameter. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide rpc_c_ns_syntax_default. group_name Specifies the RPC group that receives a new member. This can be either the global or cell-relative name. member_name_syntax An integer value that specifies the syntax of member_name. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide rpc_c_ns_syntax_default. member_name Name of the new RPC group member. This can be either the global or cell-relative name. Output status Returns the status code from this routine, indicating whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_class_version_mismatch RPC class version mismatch. rpc_s_incomplete_name Incomplete name. rpc_s_invalid_name_syntax Invalid name syntax. rpc_s_name_service_unavailable Name service unavailable. rpc_s_no_ns_permission No permission for name service operation. rpc_s_unsupported_name_syntax Unsupported name syntax. DESCRIPTION The rpc_ns_group_mbr_add() routine adds, to the name service database, an entry name as a member to the Name Service Interface (NSI) group attribute of an entry. The group_name parameter specifies the entry. If the specified group_name entry does not exist, this routine creates the entry with a group attribute and adds the group member specified by the member_name parameter. In this case, the application must have permission to create the entry. Otherwise, a management application with the necessary permissions creates the entry by calling rpc_ns_mgmt_entry_create() before the application is run. An application can add the entry in member_name to a group before it creates the entry itself. Permissions Required You need both read permission and write permission to the CDS object entry (the target group entry). If the entry does not exist, you also need insert permission to the parent directory. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_group_mbr_remove rpc_ns_mgmt_entry_create 4 rpc_ns_group_mbr_inq_begin NAME rpc_ns_group_mbr_inq_begin - Creates an inquiry context for viewing group members Used by client, server, or management applications. SYNOPSIS #include void rpc_ns_group_mbr_inq_begin( unsigned32 group_name_syntax, unsigned_char_t *group_name, unsigned32 member_name_syntax, rpc_ns_handle_t *inquiry_context, unsigned32 *status ); PARAMETERS Input group_name_syntax An integer value that specifies the syntax of the group_name parameter. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide rpc_c_ns_syntax_default. group_name Specifies the name of the RPC group to view. member_name_syntax An integer value that specifies the syntax of member_name in the rpc_ns_group_mbr_inq_next() routine. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide rpc_c_ns_syntax_default. Output inquiry_context Returns a name service handle for use with the rpc_ns_group_mbr_inq_next() and rpc_ns_group_mbr_inq_done() routines. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_incomplete_name Incomplete name. rpc_s_invalid_name_syntax Invalid name syntax. rpc_s_unsupported_name_syntax Unsupported name syntax. DESCRIPTION The rpc_ns_group_mbr_inq_begin() routine creates an inquiry context for viewing the members of an RPC group. Before calling rpc_ns_group_mbr_inq_next(), the application must first call this routine to create an inquiry context. When finished viewing the RPC group members, the application calls the rpc_ns_group_mbr_inq_done() routine to delete the inquiry context. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_group_mbr_add rpc_ns_group_mbr_inq_done rpc_ns_group_mbr_inq_next rpc_ns_mgmt_handle_set_exp_age 4 rpc_ns_group_mbr_inq_done NAME rpc_ns_group_mbr_inq_done - Deletes the inquiry context for a group Used by client, server, or management applications. SYNOPSIS #include void rpc_ns_group_mbr_inq_done( rpc_ns_handle_t *inquiry_context, unsigned32 *status ); PARAMETERS Input/Output inquiry_context Specifies the name service handle to delete. (A name service handle is created by calling rpc_ns_group_mbr_inq_begin().) Returns the value NULL. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_invalid_ns_handle Invalid name service handle. DESCRIPTION The rpc_ns_group_mbr_inq_done() routine deletes an inquiry context created by calling rpc_ns_group_mbr_inq_begin(). An application calls this routine after viewing RPC group members using the rpc_ns_group_mbr_inq_next() routine. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_group_mbr_inq_begin rpc_ns_group_mbr_inq_next 4 rpc_ns_group_mbr_inq_next NAME rpc_ns_group_mbr_inq_next - Returns one member name at a time from a group Used by client, server, or management applications. SYNOPSIS #include void rpc_ns_group_mbr_inq_next( rpc_ns_handle_t inquiry_context, unsigned_char_t **member_name, unsigned32 *status ); PARAMETERS Input inquiry_context Specifies a name service handle. This handle is returned from the rpc_ns_group_mbr_inq_begin() routine. Output member_name Returns a pointer to a (global) RPC group member name. The syntax of the returned name is specified by the member_name_syntax parameter in rpc_ns_group_mbr_inq_begin(). Specify NULL to prevent the routine from returning this parameter. In this case, the application does not call rpc_string_free(). status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_class_version_mismatch RPC class version mismatch. rpc_s_entry_not_found Name service entry not found. rpc_s_invalid_ns_handle Invalid name service handle. rpc_s_name_service_unavailable Name service unavailable. rpc_s_no_more_members No more members. rpc_s_no_ns_permission No permission for name service operation. rpc_s_not_rpc_entry Not an RPC entry. DESCRIPTION The rpc_ns_group_mbr_inq_next() routine returns one member of the RPC group specified by the group_name parameter in the rpc_ns_group_mbr_inq_begin() routine. An application can view all the members of an RPC group by calling the rpc_ns_group_mbr_inq_next() routine repeatedly. When all the group members have been viewed, this routine returns an rpc_s_no_more_members status. The returned group members are unordered. On each call to this routine that returns a member name (as a global name), the RPC runtime allocates memory for the returned member_name. The application calls rpc_string_free() for each returned member_name string. After viewing the RPC group's members, the application must call the rpc_ns_group_mbr_inq_done() routine to delete the inquiry context. Permissions Required You need read permission to the CDS object entry (the target group entry). RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_group_mbr_inq_begin rpc_ns_group_mbr_inq_done rpc_string_free 4 rpc_ns_group_mbr_remove NAME rpc_ns_group_mbr_remove - Removes an entry name from a group Used by client, server, or management applications. SYNOPSIS #include void rpc_ns_group_mbr_remove( unsigned32 group_name_syntax, unsigned_char_t *group_name, unsigned32 member_name_syntax, unsigned_char_t *member_name, unsigned32 *status ); PARAMETERS Input group_name_syntax An integer value that specifies the syntax of the group_name parameter. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide rpc_c_ns_syntax_default. group_name Specifies the RPC group from which to remove member_name. This can be either the global or cell-relative name. member_name_syntax An integer value that specifies the syntax of member_name. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide rpc_c_ns_syntax_default. member_name Specifies the member to remove from the Name Service Interface (NSI) group attribute in the group_name entry. This member can be either the global or cell-relative name. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_entry_not_found Name service entry not found. rpc_s_group_member_not_found Group member not found. rpc_s_incomplete_name Incomplete name. rpc_s_invalid_name_syntax Invalid name syntax. rpc_s_name_service_unavailable Name service unavailable. rpc_s_no_ns_permission No permission for name service operation. rpc_s_unsupported_name_syntax Unsupported name syntax. DESCRIPTION The rpc_ns_group_mbr_remove() routine removes a member from the NSI group attribute in the group_name entry. Permissions Required You need both read permission and write permission to the CDS object entry (the target group entry). RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_group_mbr_add 4 rpc_ns_import_ctx_add_eval NAME rpc_ns_import_ctx_add_eval - Adds an evaluation routine to an import context Used by client applications. SYNOPSIS #include void rpc_ns_import_ctx_add_eval( rpc_ns_handle_t *import_context, unsigned32 function_type, rpc_ns_handle_t *eval_args, void *eval_func, void *free_func, error_status_t *status ); PARAMETERS Input import_context The name service handle obtained from the rpc_ns_binding_import_begin() routine. func_type The type of evaluation function. This value currently must be rpc_cs_code_eval_func. eval_args An opaque data type that data used by the evaluation routine. Client applications adding a DCE RPC code sets evaluation routine (rpc_cs_eval_with_universal() or rpc_cs_eval_without_universal()) specify the server's NSI entry name in this parameter. eval_func A function pointer to the evaluation routine to be called from the rpc_ns_binding_import_next() routine. The void declaration for eval_func means that the function does not return a value. Client applications adding a DCE RPC code sets evaluation routine (rpc_cs_eval_with_universal() or rpc_cs_eval_without_universal()) specify the routine name in this parameter. free_func A function pointer to a routine that is invoked from rpc_ns_binding_import_done() and which performs application- specific cleanup. Client applications adding a DCE RPC code sets evaluation routine (rpc_cs_eval_with_universal() or rpc_cs_eval_without_universal()) specify NULL in this parameter. Output import_context Returns the name service handle which contains the rpc_ns_binding_import_next() and rpc_ns_binding_import_done() routines. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. rpc_s_ok Success. rpc_s_no_memory The RPC runtime could not allocate heap storage. rpc_s_invalid_ns_handle The import_context parameter was not valid. DESCRIPTION The rpc_ns_import_ctx_add_eval() routine adds an evaluation routine to an import context created by the rpc_ns_binding_import_begin() routine. The evaluation routine adds additional criteria to that used by rpc_ns_binding_import_next() (that is, protocol and interface information) for importing compatible server binding handles. Client applications call the rpc_ns_import_ctx_add_eval() routine once for each evaluation routine to be added to an import context (if there are multiple evaluation routines to be set up.) If the user-specified evaluation routine needs to perform special cleanup functions, such as deleting a temporary file from a disk, use the free_func parameter to specify the cleanup routine to be called from rpc_ns_binding_import_done(). For DCE 1.1, client applications that transfer international character data in a heterogeneous character set and code set environment use the rpc_ns_import_ctx_add_eval() routine to add one or more code sets evaluation routines to the import context returned by the rpc_ns_binding_import_begin() routine. When the client application calls the rpc_ns_binding_import_next() routine to import compatible binding handles for servers, this routine calls the code sets evaluation routine, which applies client-server character set and code sets compatibility checking as another criteria for compatible binding selection. The code sets compatibility evaluation routine specified can be one of the following: rpc_cs_eval_with_universal A DCE RPC code sets evaluation routine that evaluates character set and code sets compatibility between client and server. If client and server character sets are compatible, but their supported code sets are not, the routine sets code set tags that direct the client and/or server stubs to convert character data to either user-defined intermediate code sets (if they exist) or the DCE intermediate code set, which is the ISO 10646 (or "universal") code set. rpc_cs_eval_without_universal A DCE RPC code sets evaluation routine that evaluates character set and code sets compatibility between client and server. If client and server character sets are compatible, but their supported code sets are not, the routine attempts to return the message rpc_s_no_compat_codesets to the rpc_ns_binding_import_next() routine. application-supplied-routine A user-written code sets evaluation routine. Application developers writing internationalized DCE applications can develop their own code sets evaluation routines for client-server code sets evaluation if the DCE-supplied routines do not meet their application's needs. Restrictions Client applications that add evaluation routines to server binding import context cannot use the automatic binding method to bind to a server. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_cs_eval_with_universal rpc_cs_eval_without_universal rpc_ns_binding_import_begin rpc_ns_binding_import_done rpc_ns_binding_import_next rpc_ns_mgmt_handle_set_exp_age 4 rpc_ns_mgmt_binding_unexport NAME rpc_ns_mgmt_binding_unexport - Removes multiple binding handles, or object UUIDs, from an entry in the name service database Used by management applications. SYNOPSIS #include void rpc_ns_mgmt_binding_unexport( unsigned32 entry_name_syntax, unsigned_char_t *entry_name, rpc_if_id_t *if_id, unsigned32 vers_option, uuid_vector_t *object_uuid_vec, unsigned32 *status ); PARAMETERS Input entry_name_syntax An integer value that specifies the syntax of the entry_name parameter. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide rpc_c_ns_syntax_default. entry_name Specifies an entry name whose binding handles or object UUIDs are removed. This can be either the global or cell-relative name. if_id Specifies an interface identifier for the binding handles to be removed from the name service database. The value NULL indicates that no binding handles are removed (only object UUIDs are removed). vers_option Specifies how the rpc_ns_mgmt_binding_unexport() routine uses the vers_major and the vers_minor fields of the if_id parameter. The following table presents the accepted values for this parameter: Uses of vers_major and vers_minor fields of if_id _____________________________________________________________________ Value Description _____________________________________________________________________ rpc_c_vers_all Unexports (removes) all bindings for the interface UUID in if_id, regardless of the version numbers. For this value, specify 0 (zero) for both the major and minor versions in if_id. rpc_c_vers_compatible Removes those bindings for the interface UUID in if_id with the same major version as in if_id, and with a minor version greater than or equal to the minor ver- sion in if_id. rpc_c_vers_exact Removes those bindings for the interface UUID in if_id with the same major and minor versions as in if_id. rpc_c_vers_major_only Removes those bindings for the interface UUID in if_id with the same major version as in if_id (ignores the minor version). For this value, specify 0 (zero) for the minor version in if_id. rpc_c_vers_upto Removes those bindings that offer a version of the specified interface UUID less than or equal to the specified major and minor version. (For example, if if_id contains V2.0 and the name service entry contains binding handles with the versions V1.3, V2.0, and V2.1, the rpc_ns_mgmt- _binding_unexport() routine removes the binding handles with V1.3 and V2.0.) object_uuid_vec Specifies a vector of object UUIDs to be removed from the name service database. The application constructs this vector. The value NULL indicates that no object UUIDs are removed (only binding handles are removed). Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_entry_not_found Name service entry not found. rpc_s_incomplete_name Incomplete name. rpc_s_interface_not_found Interface not found. rpc_s_invalid_name_syntax Invalid name syntax. rpc_s_invalid_vers_option Invalid version option. rpc_s_name_service_unavailable Name service unavailable. rpc_s_no_ns_permission No permission for name service operation. rpc_s_not_all_objs_unexported Not all objects unexported. rpc_s_nothing_to_unexport Nothing to unexport. rpc_s_not_rpc_entry Not an RPC entry. rpc_s_unsupported_name_syntax Unsupported name syntax. DESCRIPTION The rpc_ns_mgmt_binding_unexport() routine allows a management application to unexport (that is, remove) one of the following from an entry in the name service database: + All the binding handles for a specified interface UUID, qualified by the interface version numbers (major and minor). + One or more object UUIDs of resources. + Both binding handles and object UUIDs of resources. A management application can remove an interface and objects in a single call to this routine, or it can remove them separately. If the rpc_ns_mgmt_binding_unexport() routine does not find any binding handles for the specified interface, the routine returns an rpc_s_interface_not_found status and does not remove the object UUIDs, if any are specified. If one or more binding handles for the specified interface are found and removed without error, rpc_ns_mgmt_binding_unexport() removes the specified object UUIDs, if any. If any of the specified object UUIDs are not found, rpc_ns_mgmt_binding_unexport() returns the rpc_not_all_objs_unexported status code. A management application, in addition to calling this routine, also calls the rpc_mgmt_ep_unregister() routine to remove any servers that have registered with the local endpoint map. Use this routine with caution, only when you expect a server to be unavailable for an extended time; for example, when it is permanently removed from service. Additionally, keep in mind that name service databases are designed to be relatively stable. In replicated name service databases, frequent use of the rpc_ns_binding_export() and rpc_ns_mgmt_binding_unexport() routines causes the name service to remove and replace the same entry repeatedly, and can cause performance problems. Permissions Required You need both read permission and write permission to the CDS object entry (the target name service entry). RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_mgmt_ep_unregister rpc_ns_binding_export rpc_ns_binding_unexport 4 rpc_ns_mgmt_entry_create NAME rpc_ns_mgmt_entry_create - Creates an entry in the name service database Used by management applications. SYNOPSIS #include void rpc_ns_mgmt_entry_create( unsigned32 entry_name_syntax, unsigned_char_t *entry_name, unsigned32 *status ); PARAMETERS Input entry_name_syntax An integer value that specifies the syntax of the entry_name parameter. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide rpc_c_ns_syntax_default. entry_name Specifies the name of the entry to create. This can be either the global or cell-relative name. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_entry_already_exists Name service entry already exists. rpc_s_incomplete_name Incomplete name. rpc_s_invalid_name_syntax Invalid name syntax. rpc_s_name_service_unavailable Name service unavailable. rpc_s_no_ns_permission No permission for name service operation. rpc_s_unsupported_name_syntax Unsupported name syntax. DESCRIPTION The rpc_ns_mgmt_entry_create() routine creates an entry in the name service database. A management application can call rpc_ns_mgmt_entry_create() to create an entry in the name service database for use by another application that does not itself have the necessary name service permissions to create an entry. Permissions Required You need both read permission and write permission to the CDS object entry (the target name service entry). You also need insert permission to the parent directory. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_mgmt_entry_delete 4 rpc_ns_mgmt_entry_delete NAME rpc_ns_mgmt_entry_delete - Deletes an entry from the name service database Used by management applications. SYNOPSIS #include void rpc_ns_mgmt_entry_delete( unsigned32 entry_name_syntax, unsigned_char_t *entry_name, unsigned32 *status ); PARAMETERS Input entry_name_syntax An integer value that specifies the syntax of the entry_name parameter. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide rpc_c_ns_syntax_default. entry_name Specifies the name of the entry to delete. This can be either the global or cell-relative name. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_entry_not_found Name service entry not found. rpc_s_incomplete_name Incomplete name. rpc_s_invalid_name_syntax Invalid name syntax. rpc_s_name_service_unavailable Name service unavailable. rpc_s_no_ns_permission No permission for name service operation. rpc_s_not_rpc_entry Not an RPC entry. rpc_s_unsupported_name_syntax Unsupported name syntax. DESCRIPTION The rpc_ns_mgmt_entry_delete() routine removes an RPC entry from the name service database. Management applications use this routine only when an entry is no longer needed, such as when a server is permanently removed from service. If the entry is a member of a group or profile, it must also be deleted from the group or profile. Use this routine cautiously. Since name service databases are designed to be relatively stable, the frequent use of rpc_ns_mgmt_entry_delete() can result in the following difficulties: + Performance problems Creating and deleting entries in client or server applications causes the name service to remove and replace the same entry repeatedly in the name service database, which can lead to performance problems. + Lost entry updates When multiple applications access a single entry through different replicas of a name service database, updates to the entry can be lost. In this situation, if one application deletes the entry and another application updates the entry before the replicas are synchronized, the delete operation takes precedence over the update operation. When the replicas are synchronized, the update is lost because the entry is deleted from all replicas. Permissions Required You need read permission to the CDS object entry (the target name service entry). You also need delete permission to the CDS object entry or to the parent directory. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_mgmt_entry_create 4 rpc_ns_mgmt_entry_inq_if_ids NAME rpc_ns_mgmt_entry_inq_if_ids - Returns the list of interfaces exported to an entry in the name service database Used by client, server, or management applications. SYNOPSIS #include void rpc_ns_mgmt_entry_inq_if_ids( unsigned32 entry_name_syntax, unsigned_char_t *entry_name, rpc_if_id_vector_t **if_id_vec, unsigned32 *status ); PARAMETERS Input entry_name_syntax An integer value that specifies the syntax of argument entry_name. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide rpc_c_ns_syntax_default. entry_name Specifies the entry in the name service database for which an interface identifier vector is returned. This can be either the global or cell-relative name. Output if_id_vec Returns the address of the interface identifier vector. status Returns the status code from this routine, indicating whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_entry_not_found Name service entry not found. rpc_s_incomplete_name Incomplete name. rpc_s_invalid_name_syntax Invalid name syntax. rpc_s_name_service_unavailable Name service unavailable. rpc_s_no_interfaces_exported No interfaces were exported to entry. rpc_s_no_ns_permission No permission for name service operation. rpc_s_unsupported_name_syntax Unsupported name syntax. DESCRIPTION The rpc_ns_mgmt_entry_inq_if_ids() routine returns an interface identifier vector containing the interfaces of binding handles exported to argument entry_name. This routine uses an expiration age of 0 (zero) to cause an immediate update of the local copy of name service data. The rpc_ns_mgmt_inq_exp_age() routine's reference page contains an explanation of the expiration age. The application calls rpc_if_id_vector_free() to release memory used by the returned vector. Permissions Required You need read permission to the CDS object entry (the target name service entry). RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_if_id_vector_free rpc_if_inq_id rpc_ns_binding_export 4 rpc_ns_mgmt_free_codesets NAME rpc_ns_mgmt_free_codesets - Frees a code sets array that has been allocated by the RPC runtime Used by client and server applications. SYNOPSIS #include void rpc_ns_mgmt_free_codesets( rpc_codeset_mgmt_p_t *code_sets_array, error_status_t *status ); PARAMETERS Input/Output code_sets_array A pointer to a code sets array that has been allocated by a call to the rpc_ns_mgmt_read_codesets() routine or the rpc_rgy_get_codesets() routine. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. DESCRIPTION The rpc_ns_mgmt_free_codesets() routine belongs to a set of DCE RPC routines for character and code set interoperability. These routines permit client and server applications to transfer international character data in a heterogeneous character set and code sets environment. The rpc_ns_mgmt_free_codesets() routine frees from the client application's memory a code sets array allocated by a client call to the rpc_ns_mgmt_read_codesets() or the rpc_rgy_get_codesets() routines. The routine frees from a server application's memory a code sets array allocated by a server call to the rpc_rgy_get_codesets() routine. Client applications use the rpc_ns_mgmt_read_codesets() routine to retrieve a server's supported code sets in order to evaluate them against the code sets that the client supports. Clients and servers use the rpc_rgy_get_codesets() routine to get their supported code sets from the code set registery. Clients and servers use the rpc_ns_mgmt_free_codesets() routine to free the memory allocated to the code sets array as part of their cleanup procedures. Permissions Required None. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_mgmt_read_codesets rpc_rgy_get_codesets 4 rpc_ns_mgmt_handle_set_exp_age NAME rpc_ns_mgmt_handle_set_exp_age - Sets a handle's expiration age for local copies of name service data Used by client, server, or management applications. SYNOPSIS #include void rpc_ns_mgmt_handle_set_exp_age( rpc_ns_handle_t ns_handle, unsigned32 expiration_age, unsigned32 *status ); PARAMETERS Input ns_handle Specifies the name service handle for which you supply an expiration age. An RPC Name Service Interface (NSI) inquiry begin operation returns a name service handle. An example is the operation that rpc_ns_entry_object_inq_begin() performs; it returns a name service handle in its inquiry_context parameter. expiration_age This integer value specifies the expiration age, in seconds, of local name service data. This data is read by all RPC NSI next routines that use the specified ns_handle parameter. An example is the rpc_ns_entry_object_inq_next() routine; it accepts a name service handle in its inquiry_context parameter. An expiration age of 0 (zero) causes an immediate update of the local name service data. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_invalid_ns_handle Invalid name service handle. DESCRIPTION The rpc_ns_mgmt_handle_set_exp_age() routine sets an expiration age for a specified name service handle (in ns_handle). The expiration age is the amount of time, in seconds, that a local copy of data from a name service attribute can exist, before a request from the application for the attribute requires updating the local copy. When an application begins running, the RPC runtime specifies a random value of between 8 and 12 hours as the default expiration age. The default is global to the application. An expiration age applies only to a specific name service handle and temporarily overrides the current global expiration age. Normally, avoid using this routine; instead, rely on the application's global expiration age. A handle's expiration age is used exclusively by RPC NSI next operations (which read data from name service attributes). A next operation normally starts by looking for a local copy of the attribute data being requested by an application. In the absence of a local copy, the next operation creates one with fresh attribute data from the name service database. If a local copy already exists, the operation compares its actual age to the expiration age being used by the application (which in this case is the expiration age set for the name service handle). If the actual age exceeds the handle's expiration age, the operation automatically tries to update the local copy with fresh attribute data. If updating is impossible, the old local data remains in place and the next operation fails, returning the rpc_s_name_service_unavailable status code. The scope of a handle's expiration age is a single series of RPC NSI next operations. The rpc_ns_mgmt_handle_set_exp_age() routine operates as follows: 1. An RPC NSI begin operation, such as the one performed by rpc_ns_group_mbr_inq_begin() creates a name service handle. 2. A call to rpc_ns_mgmt_handle_set_exp_age() creates an expiration age for the handle. 3. A series of corresponding RPC NSI next operations for the name service handle uses the handle's expiration age. 4. A corresponding RPC NSI done operation for the name service handle deletes both the handle and its expiration age. Permissions Required No permissions are required. CAUTIONS Use this routine with extreme caution. Setting the handle's expiration age to a small value causes the RPC NSI next operations to frequently update local data for any name service attribute requested by your application. For example, setting the expiration age to 0 (zero) forces the next operation to update local data for the name service attribute requested by your application. Therefore, setting a small expiration age for a name service handle can create performance problems for your application. Also, if your application is using a remote server with the name service database, a small expiration age can adversely affect network performance for all applications. Limit the use of this routine to the following types of situations: + When you must always get accurate name service data. For example, during management operations to update a profile, you may need to always see the profile's current contents. In this case, before beginning to inquire about a profile, your application must call rpc_ns_mgmt_handle_set_exp_age() and specify 0 (zero) for the expiration_age parameter. + When a request using the default expiration age fails, and your application needs to retry the operation. For example, a client application using import must first try to obtain bindings using the application's default expiration age. However, sometimes the import-next operation returns either no binding handles or an insufficient number of them. In this case, the client can retry the import operation and, after rpc_ns_binding_import_begin() terminates, include a rpc_ns_mgmt_handle_set_exp_age() routine that specifies 0 (zero) for the expiration_age parameter. When the client calls the import-next routine again, the small expiration age for the name service handle causes the import-next operation to update the local attribute data. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_binding_import_begin rpc_ns_binding_lookup_begin rpc_ns_entry_object_inq_begin rpc_ns_group_mbr_inq_begin rpc_ns_mgmt_inq_exp_age rpc_ns_mgmt_set_exp_age rpc_ns_profile_elt_inq_begin 4 rpc_ns_mgmt_inq_exp_age NAME rpc_ns_mgmt_inq_exp_age - Returns the application's global expiration age for local copies of name service data Used by client, server, or management applications. SYNOPSIS #include void rpc_ns_mgmt_inq_exp_age( unsigned32 *expiration_age, unsigned32 *status ); PARAMETERS Input None. Output expiration_age Returns the default expiration age (in seconds). All the RPC Name Service Interface (NSI) read operations (all the next operations) use this value. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status code and its meaning is as follows: rpc_s_ok Success. DESCRIPTION The rpc_ns_mgmt_inq_exp_age() routine returns the global expiration age that the application is using. The expiration_age parameter represents the amount of time, in seconds, that a local copy of data from a name service attribute can exist before a request from the application for the attribute requires updating the local copy. When an application begins running, the RPC runtime specifies a random value of between 8 and 12 hours as the default expiration age. The default is global to the application. The RPC NSI next operations, which read data from name service attributes, use an expiration age. A next operation normally starts by looking for a local copy of the attribute data that an application requests. In the absence of a local copy, the next operation creates one with fresh attribute data from the name service database. If a local copy already exists, the operation compares its actual age to the expiration age being used by the application. If the actual age exceeds the expiration age, the operation automatically tries to update the local copy with fresh attribute data from the name service database. If updating is impossible, the old local data remains in place and the next operation fails, returning the rpc_s_name_service_unavailable status code. Applications normally use only the default expiration age. For special cases, an application can substitute a user-supplied global expiration age for the default by calling rpc_ns_mgmt_set_exp_age(). The rpc_ns_mgmt_inq_exp_age() routine returns the current global expiration age, whether it is a default or a user-supplied value. An application can also override the global expiration age temporarily by calling rpc_ns_mgmt_handle_set_exp_age(). Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_mgmt_handle_set_exp_age rpc_ns_mgmt_set_exp_age 4 rpc_ns_mgmt_read_codesets NAME rpc_ns_mgmt_read_codesets - Reads the code sets attribute associated with an RPC server entry in the name service database. Used by client applications. SYNOPSIS #include void rpc_ns_mgmt_read_codesets( unsigned32 entry_name_syntax, unsigned_char_t *entry_name, rpc_codeset_mgmt_p_t *code_sets_array, error_status_t *status ); PARAMETERS Input entry_name_syntax An integer value that specifies the syntax of the entry_name parameter. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide rpc_c_ns_syntax_default. entry_name Specifies the name of the RPC server entry in the name service database from which to read the code sets attribute. The name can be either the global or cell-relative name. Output code_sets_array A code sets array that specifies the code sets that the RPC server supports. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok rpc_s_invalid_name_syntax rpc_s_mgmt_bad_type rpc_s_name_service_unavailable rpc_s_no_permission rpc_s_incomplete_name rpc_s_no_memory DESCRIPTION The rpc_ns_mgmt_read_codesets() routine belongs to a set of DCE RPC routines for character and code set interoperability. These routines permit client and server applications to transfer international character data in a heterogeneous character set and code sets environment. The rpc_ns_mgmt_read_codesets() routine reads the code sets attribute associated with an RPC server entry in the name service database. The routine takes the name of an RPC server entry and returns a code sets array that corresponds to the code sets that this RPC server supports. Client applications use the rpc_ns_mgmt_read_codesets() routine to retrieve a server's supported code sets in order to evaluate them against the code sets that the client supports. Client applications that use the evaluation routines rpc_cs_eval_with_universal() and rpc_cs_eval_without_universal() do not need to call this routine explicitly, because these code sets evaluation routines call it on the client's behalf. Application developers who are writing their own character and code set evaluation routines may need to include rpc_ns_mgmt_read_codesets() in their user-written evaluation routines. Permissions Required You need read permission to the target RPC server entry (which is a CDS object). RETURN VALUES No value is returned. RELATED INFORMATION Functions: dce_cs_rgy_to_loc dce_cs_loc_to_rgy rpc_ns_mgmt_free_codesets rpc_ns_mgmt_remove_attribute rpc_ns_mgmt_set_attribute rpc_rgy_get_codesets rpc_rgy_get_max_bytes 4 rpc_ns_mgmt_remove_attribute NAME rpc_ns_mgmt_remove_attribute - Removes an attribute from an RPC server entry in the name service database. Used mainly by server applications; can also be used by management applications. SYNOPSIS #include #include void rpc_ns_mgmt_remove_attribute( unsigned32 entry_name_syntax, unsigned_char_t *entry_name, uuid_t *attr_type, error_status_t *status ); PARAMETERS Input entry_name_syntax An integer value that specifies the syntax of the entry_name parameter. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide rpc_c_ns_syntax_default. entry_name Specifies the name of the RPC server entry in the name service database from which the attribute will be removed. The name can be either the global or cell-relative name. If you are using this routine to remove a code sets attribute from an RPC server entry in the Cell Directory Service database, then this parameter specifies the CDS name of the server entry that contains the code sets attribute to be removed. attr_type A UUID that specifies the attribute type. For DCE 1.1, this value must be rpc_c_attr_codesets. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_entry_not_found The routine cannot find the RPC server entry specified in the call in the name service database. rpc_s_incomplete_name The routine cannot expand the RPC server entry name specified in the call. rpc_s_invalid_name_syntax The name syntax specified in the call is not valid. rpc_s_mgmt_bad_type The attribute type specified in the call does not match that of the attribute to be removed from the name service database. rpc_s_name_service_unavailable The routine was unable to communicate with the name service. rpc_s_no_ns_permission The routine's caller does not have the proper permission for an NSI operation. DESCRIPTION The rpc_ns_mgmt_remove_attribute() routine belongs to a set of DCE RPC routines for use by client and server applications that are transferring international character data in a heterogeneous character set and code sets environment. The rpc_ns_mgmt_remove_attribute() routine is designed to be a generic routine for removing an attribute from an RPC server entry in the name service database. The routine removes the attribute from the specified RPC server entry in the name service database. The routine does not remove the RPC server entry. For DCE 1.1, you use rpc_ns_mgmt_remove_attribute() in your application server initialization routine or signal handling routine to remove a code sets attribute from the server's entry in the Cell Directory Service database as part of the server cleanup procedure carried out prior to the server's termination. A management application can call rpc_ns_mgmt_remove_attribute() to remove an attribute from an RPC server entry in the name service database on behalf of an application that does not itself have the necessary name service permissions to remove one. Permissions Required You need write permission to the target RPC server entry (which is a CDS object). RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_mgmt_read_codesets rpc_ns_mgmt_set_attribute rpc_rgy_get_codesets 4 rpc_ns_mgmt_set_attribute NAME rpc_ns_mgmt_set_attribute - Adds an attribute to an RPC server entry in the name service database. Used mainly by server applications; can also be used by management applications. SYNOPSIS #include #include void rpc_ns_mgmt_set_attribute( unsigned32 entry_name_syntax, unsigned_char_t *entry_name, uuid_t *attr_type, void *attr_value, error_status_t *status ); PARAMETERS Input entry_name_syntax An integer value that specifies the syntax of the entry_name parameter. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide rpc_c_ns_syntax_default. entry_name Specifies the name of the RPC server entry in the name service database with which the attribute will be associated. The name can be either the global or cell-relative name. If you are using this routine to add a code sets attribute to an RPC server entry in the name service database, then this parameter specifies the name of the server entry with which the code sets attribute will be associated. attr_type A UUID that specifies the attribute type. For DCE 1.1, this value must be rpc_c_attr_codesets. attr_val An opaque data structure that specifies the attribute value to be stored in the name service database. If you are using this routine to add a code sets attribute to an RPC server entry, you must cast the representation of the code set data from the data type rpc_codeset_mgmt_p_t to the data type void*. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_invalid_name_syntax The name syntax specified in the call is not valid. rpc_s_mgmt_bad_type The attribute type specified in the call does not match that of the attribute to be added to the name service database. rpc_s_no_memory The routine was unable to allocate memory to encode the value. rpc_s_name_service_unavailable The routine was unable to communicate with the name service. rpc_s_no_ns_permission The routine's caller does not have the proper permission for an NSI operation. DESCRIPTION The rpc_ns_mgmt_set_attribute() routine belongs to a set of DCE RPC routines for use by client and server applications that are transferring international character data in a heterogeneous character set and code sets environment. The rpc_ns_mgmt_set_attribute() routine is designed to be a generic routine for adding an attribute to an RPC server entry in the name service database. The routine takes an attribute type and a pointer to the value, and stores the attribute value in the name service database. For DCE 1.1, you use rpc_ns_mgmt_set_attribute() in your application server initialization routine to add a code sets attribute to the server's entry in the Cell Directory Service database (which the initialization routine has created with the rpc_ns_binding_export() routine). Because CDS stores integer values in little-endian format, the rpc_ns_mgmt_set_attribute() routine also encodes the code sets attribute value into an endian-safe format before storing it in the name service database. A management application can call rpc_ns_mgmt_set_attribute() to add an attribute to an RPC server entry in the name service database on behalf of an application that does not itself have the necessary name service permissions to add one. Permissions Required You need both read permission and write permission to the target RPC server entry (which is a CDS object). You also need insert permission to the parent directory. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_mgmt_read_codesets rpc_ns_mgmt_remove_attribute rpc_rgy_get_codesets 4 rpc_ns_mgmt_set_exp_age NAME rpc_ns_mgmt_set_exp_age - Modifies the application's global expiration age for local copies of name service data Used by client, server, or management applications. SYNOPSIS #include void rpc_ns_mgmt_set_exp_age( unsigned32 expiration_age, unsigned32 *status ); PARAMETERS Input expiration_age An integer value that specifies the default expiration age, in seconds, for local name service data. This expiration age applies to all RPC name service interface (NSI) read operations (all the next operations). An expiration age of 0 (zero) causes an immediate update of the local name service data. To reset the expiration age to an RPC-assigned random value between 8 and 12 hours, specify a value of rpc_c_ns_default_exp_age. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status code and its meaning is as follows: rpc_s_ok Success. DESCRIPTION The rpc_ns_mgmt_set_exp_age() routine modifies the global expiration age that the application is using. The expiration_age parameter represents the amount of time, in seconds, that a local copy of data from a name service attribute can exist before a request from the application for the attribute requires updating the local copy. When an application begins running, the RPC runtime specifies a random value of between 8 and 12 hours as the default expiration age. The default is global to the application. Normally, you should avoid using this routine; instead, rely on the default expiration age. The RPC NSI next operations, which read data from name service attributes, use an expiration age. A next operation normally starts by looking for a local copy of the attribute data that an application requests. In the absence of a local copy, the next operation creates one with fresh attribute data from the name service database. If a local copy already exists, the operation compares its actual age to the expiration age being used by the application. If the actual age exceeds the expiration age, the operation automatically tries to update the local copy with fresh attribute data from the name service database. If updating is impossible, the old local data remains in place and the next operation fails, returning the rpc_s_name_service_unavailable status code. Permissions Required No permissions are required. CAUTIONS Use this routine with extreme caution. Setting the expiration age to a small value causes the RPC NSI next operations to frequently update local data for any name service attribute that your application requests. For example, setting the expiration age to 0 (zero) forces all next operations to update local data for the name service attribute that your application has requested. Therefore, setting small expiration ages can create performance problems for your application. Also, if your application is using a remote server with the name service database, a small expiration age can adversely affect network performance for all applications. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_mgmt_handle_set_exp_age rpc_ns_mgmt_set_exp_age 4 rpc_ns_profile_delete NAME rpc_ns_profile_delete - Deletes a profile attribute Used by client, server, or management applications. SYNOPSIS #include void rpc_ns_profile_delete( unsigned32 profile_name_syntax, unsigned_char_t *profile_name, unsigned32 *status ); PARAMETERS Input profile_name_syntax An integer value that specifies the syntax of the profile_name parameter. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide rpc_c_ns_syntax_default. profile_name Specifies the name of the profile to delete. This can be either the global or cell-relative name. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_entry_not_found Name service entry not found. rpc_s_incomplete_name Incomplete name. rpc_s_invalid_name_syntax Invalid name syntax. rpc_s_name_service_unavailable Name service unavailable. rpc_s_no_ns_permission No permission for name service operation. rpc_s_unsupported_name_syntax Unsupported name syntax. DESCRIPTION The rpc_ns_profile_delete() routine deletes the profile attribute from the specified entry in the name service database (the profile_name parameter). Neither the specified entry nor the entry names included as members in each profile element are deleted. Use this routine cautiously; deleting a profile may break a hierarchy of profiles. Permissions Required You need write permission to the CDS object entry (the target profile entry). RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_profile_elt_add rpc_ns_profile_elt_remove 4 rpc_ns_profile_elt_add NAME rpc_ns_profile_elt_add - Adds an element to a profile; if necessary, creates the entry Used by client, server, or management applications. SYNOPSIS #include void rpc_ns_profile_elt_add( unsigned32 profile_name_syntax, unsigned_char_t *profile_name, rpc_if_id_t *if_id, unsigned32 member_name_syntax, unsigned_char_t *member_name, unsigned32 priority, unsigned_char_t *annotation, unsigned32 *status ); PARAMETERS Input profile_name_syntax An integer value that specifies the syntax of the profile_name parameter. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide rpc_c_ns_syntax_default. profile_name Specifies the RPC profile that receives a new element. This can be either the global or cell-relative name. if_id Specifies the interface identifier of the new profile element. To add or replace the default profile element, specify NULL. member_name_syntax An integer value that specifies the syntax of member_name. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide rpc_c_ns_syntax_default. member_name Specifies the entry in the name service database to include in the new profile element. This can be either the global or cell- relative name. priority An integer value (0 to 7) that specifies the relative priority for using the new profile element during the import and lookup operations. A value of 0 (zero) is the highest priority. A value of 7 is the lowest priority. Two or more elements can have the same priority. When adding the default profile member, use a value of 0 (zero). annotation Specifies an annotation string that is stored as part of the new profile element. The string can be up to 17 characters long. Specify NULL or the string \0 if there is no annotation string. The string is used by applications for informational purposes only. For example, an application can use this string to store the interface name string (specified in the IDL file). DCE RPC does not use this string during lookup or import operations, or for enumerating profile elements. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_class_version_mismatch RPC class version mismatch. rpc_s_incomplete_name Incomplete name. rpc_s_invalid_name_syntax Invalid name syntax. rpc_s_invalid_priority Invalid profile element priority. rpc_s_name_service_unavailable Name service unavailable. rpc_s_no_ns_permission No permission for name service operation. rpc_s_unsupported_name_syntax Unsupported name syntax. DESCRIPTION The rpc_ns_profile_elt_add() routine adds an element to the profile attribute of the entry in the name service database specified by the profile_name parameter. If the profile_name entry does not exist, this routine creates the entry with a profile attribute and adds the profile element specified by the if_id, member_name, priority, and annotation parameters. In this case, the application must have permission to create the entry. Otherwise, a management application with the necessary permissions creates the entry by calling rpc_ns_mgmt_entry_create() before the application is run. If an element with the specified member name and interface identifier are already in the profile, this routine updates the element's priority and annotation string using the values provided in the priority and annotation parameters. An application can add the entry in the member_name parameter to a profile before it creates the entry itself. Permissions Required You need both read permission and write permission to the CDS object entry (the target profile entry). If the entry does not exist, you also need insert permission to the parent directory. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_if_inq_id rpc_ns_mgmt_entry_create rpc_ns_profile_elt_remove 4 rpc_ns_profile_elt_inq_begin NAME rpc_ns_profile_elt_inq_begin - Creates an inquiry context for viewing the elements in a profile Used by client, server, or management applications. SYNOPSIS #include void rpc_ns_profile_elt_inq_begin( unsigned32 profile_name_syntax, unsigned_char_t *profile_name, unsigned32 inquiry_type, rpc_if_id_t *if_id, unsigned32 vers_option, unsigned32 member_name_syntax, unsigned_char_t *member_name, rpc_ns_handle_t *inquiry_context, unsigned32 *status ); PARAMETERS Input profile_name_syntax An integer value that specifies the syntax of the profile_name parameter. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide rpc_c_ns_syntax_default. profile_name Specifies the name of the profile to view. This can be either the global or cell-relative name. inquiry_type An integer value that specifies the type of inquiry to perform on the profile. The following table describes the valid inquiry types: Valid Values of inquiry_type _____________________________________________________________________ Value Description _____________________________________________________________________ rpc_c_profile_default_elt Searches the profile for the default profile element, if any. The if_id, vers_option, and member_name parameters are ignored. rpc_c_profile_all_elts Returns every element from the pro- file. The if_id, vers_option, and member_name parameters are ignored. rpc_c_profile_match_by_if Searches the profile for those ele- ments that contain the interface identifier specified by the if_id and vers_option values. The member_name parameter is ignored. rpc_c_profile_match_by_mbr Searches the profile for those ele- ments that contain the member name specified by the member_name param- eter. The if_id and vers_option parameters are ignored. rpc_c_profile_match_by_both Searches the profile for those ele- ments that contain the interface identifier and member name speci- fied by the if_id, vers_option, and member_name parameters. if_id Specifies the interface identifier of the profile elements to be returned by rpc_ns_profile_elt_inq_next(). This parameter is used only when specifying a value of either rpc_c_profile_match_by_if or rpc_c_profile_match_by_both for the inquiry_type parameter. Otherwise, this parameter is ignored and you can specify the value NULL. vers_option Specifies how rpc_ns_profile_elt_inq_next() uses the if_id parameter. This parameter is used only when specifying a value of either rpc_c_profile_match_by_if or rpc_c_profile_match_by_both for the inquiry_type parameter. Otherwise, this parameter is ignored and you can specify the value 0 (zero). The following table describes the valid values for this parameter: Valid Values of vers_option _____________________________________________________________________ Value Description _____________________________________________________________________ rpc_c_vers_all Returns profile elements that offer the specified interface UUID, regardless of the version numbers. For this value, specify 0 (zero) for both the major and minor ver- sions in if_id. rpc_c_vers_compatible Returns profile elements that offer the same major version of the specified interface UUID and a minor version greater than or equal to the minor version of the speci- fied interface UUID. rpc_c_vers_exact Returns profile elements that offer the specified version of the speci- fied interface UUID. rpc_c_vers_major_only Returns profile elements that offer the same major version of the specified interface UUID (ignores the minor version). For this value, specify 0 (zero) for the minor version in if_id. rpc_c_vers_upto Returns profile elements that offer a version of the specified inter- face UUID less than or equal to the specified major and minor version. (For example, if if_id contains V2.0 and the profile contains ele- ments with the versions V1.3, V2.0, and V2.1, rpc_ns_profile_elt_inq_next() returns the elements with V1.3 and V2.0.) member_name_syntax An integer value that specifies the syntax of the member_name parameter in this routine and the syntax of the member_name parameter in rpc_ns_profile_elt_inq_next(). To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide rpc_c_ns_syntax_default. member_name Specifies the member name that rpc_ns_profile_elt_inq_next() looks for in profile elements. This can be either the global or cell-relative name. This parameter is used only when specifying a value of either rpc_c_profile_match_by_mbr or rpc_c_profile_match_by_both for the inquiry_type parameter. Otherwise, this parameter is ignored and you specify the value NULL. Output inquiry_context Returns a name service handle for use with the rpc_ns_profile_elt_inq_next() and rpc_ns_profile_elt_inq_done() routines. status Returns the status code from this routine, indicating indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_incomplete_name Incomplete name. rpc_s_invalid_inquiry_type Invalid inquiry type. rpc_s_invalid_name_syntax Invalid name syntax. rpc_s_invalid_vers_option Invalid version option. rpc_s_unsupported_name_syntax Unsupported name syntax. DESCRIPTION The rpc_ns_profile_elt_inq_begin() routine creates an inquiry context for viewing the elements in a profile. Using the inquiry_type and vers_option parameters, an application specifies which of the following profile elements will be returned from calls to rpc_ns_profile_elt_inq_next(): + The default element. + All elements. + Those elements with the specified interface identifier. + Those elements with the specified member name. + Those elements with both the specified interface identifier and member name. Before calling rpc_ns_profile_elt_inq_next(), the application must first call this routine to create an inquiry context. When finished viewing the profile elements, the application calls the rpc_ns_profile_elt_inq_done() routine to delete the inquiry context. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_if_inq_id rpc_ns_mgmt_handle_set_exp_age rpc_ns_profile_elt_inq_done rpc_ns_profile_elt_inq_next 4 rpc_ns_profile_elt_inq_done NAME rpc_ns_profile_elt_inq_done - Deletes the inquiry context for a profile Used by client, server, or management applications. SYNOPSIS #include void rpc_ns_profile_elt_inq_done( rpc_ns_handle_t *inquiry_context, unsigned32 *status ); PARAMETERS Input/Output inquiry_context Specifies the name service handle to delete. (A name service handle is created by calling rpc_ns_profile_elt_inq_begin().) Returns the value NULL. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_invalid_ns_handle Invalid name service handle. DESCRIPTION The rpc_ns_profile_elt_inq_done() routine deletes an inquiry context created by calling rpc_ns_profile_elt_inq_begin(). An application calls this routine after viewing profile elements using the rpc_ns_profile_elt_inq_next() routine. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_profile_elt_inq_begin rpc_ns_profile_elt_inq_next 4 rpc_ns_profile_elt_inq_next NAME rpc_ns_profile_elt_inq_next - Returns one element at a time from a profile Used by client, server, or management applications. SYNOPSIS #include void rpc_ns_profile_elt_inq_next( rpc_ns_handle_t inquiry_context, rpc_if_id_t *if_id, unsigned_char_t **member_name, unsigned32 *priority, unsigned_char_t **annotation, unsigned32 *status ); PARAMETERS Input inquiry_context Specifies a name service handle. This handle is returned from the rpc_ns_profile_elt_inq_begin() routine. Output if_id Returns the interface identifier of the profile element. member_name Returns a pointer to the profile element's member name. The name is a global name. The syntax of the returned name is specified by the member_name_syntax parameter in rpc_ns_profile_elt_inq_begin(). Specify NULL to prevent the routine from returning this parameter. In this case the application does not call rpc_string_free(). priority Returns the profile element priority. annotation Returns the annotation string for the profile element. If there is no annotation string in the profile element, the string \0 is returned. Specify NULL to prevent the routine from returning this parameter. In this case the application does not need to call the rpc_string_free() routine. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_class_version_mismatch RPC class version mismatch. rpc_s_entry_not_found Name service entry not found. rpc_s_incomplete_name Incomplete name. rpc_s_invalid_ns_handle Invalid name service handle. rpc_s_name_service_unavailable Name service unavailable. rpc_s_no_more_elements No more elements. rpc_s_no_ns_permission No permission for name service operation. rpc_s_not_rpc_entry Not an RPC entry. DESCRIPTION The rpc_ns_profile_elt_inq_next() routine returns one element from the profile specified by the profile_name parameter in the rpc_ns_profile_elt_inq_begin() routine. The selection criteria for the element returned are based on the inquiry_type parameter in the rpc_ns_profile_elt_inq_begin() routine. The rpc_ns_profile_elt_inq_next() routine returns all the components (interface identifier, member name, priority, annotation string) of a profile element. An application can view all the selected profile entries by repeatedly calling the rpc_ns_profile_elt_inq_next() routine. When all the elements have been viewed, this routine returns an rpc_s_no_more_elements status code. The returned elements are unordered. On each call to this routine that returns a profile element, the DCE RPC runtime allocates memory for the returned member_name (which points to a global name) and annotation strings. The application is responsible for calling the rpc_string_free() routine for each returned member_name and annotation string. After viewing the profile's elements, the application must call the rpc_ns_profile_elt_inq_done() routine to delete the inquiry context. Permissions Required You need read permission to the CDS object entry (the target profile entry). RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_profile_elt_begin rpc_ns_profile_elt_done rpc_string_free 4 rpc_ns_profile_elt_remove NAME rpc_ns_profile_elt_remove - Removes an element from a profile Used by client, server, or management applications. SYNOPSIS #include void rpc_ns_profile_elt_remove( unsigned32 profile_name_syntax, unsigned_char_t *profile_name, rpc_if_id_t *if_id, unsigned32 member_name_syntax, unsigned_char_t *member_name, unsigned32 *status ); PARAMETERS Input profile_name_syntax An integer value that specifies the syntax of the profile_name parameter. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide rpc_c_ns_syntax_default. profile_name Specifies the profile from which to remove an element. This can be either the global or cell-relative name. if_id Specifies the interface identifier of the profile element to be removed. Specify NULL to remove the default profile member. member_name_syntax An integer value that specifies the syntax of member_name. To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide rpc_c_ns_syntax_default. member_name Specifies the name service entry name in the profile element to remove. This can be either the global or cell-relative name. When if_id is NULL, this argument is ignored. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_entry_not_found Name service entry not found. rpc_s_incomplete_name Incomplete name. rpc_s_invalid_name_syntax Invalid name syntax. rpc_s_name_service_unavailable Name service unavailable. rpc_s_no_ns_permission No permission for name service operation. rpc_s_profile_element_not_found Profile element not found. rpc_s_unsupported_name_syntax Unsupported name syntax. DESCRIPTION The rpc_ns_profile_elt_remove() routine removes a profile element from the profile specified by profile_name. Unless if_id is NULL, the member_name parameter and the if_id parameter must match the corresponding profile element attributes exactly for an element to be removed. When if_id is NULL, the default profile element is removed, and the member_name argument is ignored. The routine removes the reference to the entry specified by member_name from the profile; it does not delete the entry itself. Use this routine cautiously; removing elements from a profile may break a hierarchy of profiles. Permissions Required You need both read permission and write permission to the CDS object entry (the target profile entry). RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ns_profile_delete rpc_ns_profile_elt_add 4 rpc_object_inq_type NAME rpc_object_inq_type - Returns the type of an object Used by server applications. SYNOPSIS #include void rpc_object_inq_type( uuid_t *obj_uuid, uuid_t *type_uuid, unsigned32 *status ); PARAMETERS Input obj_uuid Specifies the object UUID whose associated type UUID is returned. Supply NULL to specify a nil UUID for this parameter. Output type_uuid Returns the type UUID corresponding to the object UUID supplied in the obj_uuid parameter. Specifying NULL here prevents the return of a type UUID. An application, by specifying NULL here, can determine from the value returned in status whether obj_uuid is registered. This determination occurs without the application specifying an output type UUID variable. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_object_not_found Object not found. uuid_s_bad_version Bad UUID version. DESCRIPTION A server application calls the rpc_object_inq_type() routine to obtain the type UUID of an object. If the object is registered with the RPC runtime using the rpc_object_set_type() routine, the registered type is returned. Optionally, an application can maintain an object/type registration privately. In this case, if the application provides an object inquiry function (see the rpc_object_set_inq_fn reference page), the RPC runtime uses that function to determine an object's type. The table below shows how rpc_object_inq_type() obtains the returned type UUID. Rules for Returning an Object's Type _____________________________________________________________________ Was object UUID Was an object inquiry registered (using function registered(using rpc_object_set_type)? rpc_object_set_inq_fn)? Return Value _____________________________________________________________________ Yes Ignored Returns the object's registered type UUID. No Yes Returns the type UUID returned from calling the inquiry function. No No Returns the nil UUID. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_object_set_inq_fn rpc_object_set_type 4 rpc_object_set_inq_fn NAME rpc_object_set_inq_fn - Registers an object inquiry function Used by server applications. SYNOPSIS #include void rpc_object_set_inq_fn( rpc_object_inq_fn_t inquiry_fn, unsigned32 *status ); PARAMETERS Input inquiry_fn Specifies a pointer to an object type inquiry function. When an application calls the rpc_object_inq_type() routine and the RPC runtime finds that the specified object is not registered, the runtime automatically calls the rpc_object_inq_type() routine to determine the object's type. Specify NULL to remove a previously set inquiry function. The following C language definition for rpc_object_inq_fn_t illustrates the prototype for this function: typedef void (*rpc_object_inq_fn_t) ( uuid_t *object_uuid, /* in */ uuid_t *type_uuid, /* out */ unsigned32 *status /* out */ ); The returned type_uuid and status values are returned as the output arguments from the rpc_object_inq_type() routine. If you specify NULL, the rpc_object_set_inq_fn() routine unregisters (that is, removes) a previously registered object type inquiry function. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status code and its meaning is as follows: rpc_s_ok Success. DESCRIPTION A server application calls rpc_object_set_inq_fn() to specify a function to determine an object's type. If an application privately maintains object/type registrations, the specified inquiry function returns the type UUID of an object from that registration. The RPC runtime automatically calls the inquiry function when the application calls rpc_object_inq_type() and the object was not previously registered by rpc_object_set_type(). The RPC runtime also automatically calls the inquiry function for every remote procedure call it receives if the object was not previously registered. Cautions Use this routine with caution. When the RPC runtime automatically calls this routine in response to a received remote procedure call, the inquiry function can be called from the context of runtime internal threads with runtime internal locks held. The inquiry function should not block or at least not block for long (for example, the inquiry function should not perform a remote procedure call). Also, the inquiry function must not unwind because of an exception. In general, the inquiry function should not call back into the RPC runtime. It is legal to call rpc_object_set_type() or any of the uuid_* routines. Failure to comply with these restrictions will result in undefined behavior. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_object_inq_type rpc_object_set_type 4 rpc_object_set_type NAME rpc_object_set_type - Registers the type of an object with the RPC runtime Used by server applications. SYNOPSIS #include void rpc_object_set_type( uuid_t *obj_uuid, uuid_t *type_uuid, unsigned32 *status ); PARAMETERS Input obj_uuid Specifies an object UUID to associate with the type UUID in the type_uuid parameter. Do not specify NULL or a nil UUID. type_uuid Specifies the type UUID of the obj_uuid parameter. Specify an argument value of NULL or a nil UUID to reset the object type to the default association of object UUID/nil type UUID. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_already_registered Object already registered. rpc_s_invalid_object Invalid object. uuid_s_bad_version Bad UUID version. DESCRIPTION The rpc_object_set_type() routine assigns a type UUID to an object UUID. By default, the RPC runtime assumes that the type of all objects is nil. A server program that contains one implementation of an interface (one manager entry point vector) does not need to call this routine, provided that the server registered the interface with the nil type UUID (see the rpc_server_register_if reference page). A server program that contains multiple implementations of an interface (multiple manager entry point vectors; that is, multiple type UUIDs) calls this routine once for each object UUID the server offers. Associating each object with a type UUID tells the RPC runtime which manager entry point vector (interface implementation) to use when the server receives a remote procedure call for a non-nil object UUID. The RPC runtime allows an application to set the type for an unlimited number of objects. To remove the association between an object UUID and its type UUID (established by calling this routine), a server calls this routine again and specifies the value NULL or a nil UUID for the type_uuid parameter. This resets the association between an object UUID and type UUID to the default. A server cannot register a nil object UUID. The RPC runtime automatically registers the nil object UUID with a nil type UUID. Attempting to set the type of a nil object UUID will result in the routine's returning the status code rpc_s_invalid_object. Servers that want to maintain their own object UUID to type UUID mapping can use rpc_object_set_inq_fn() in place of, or in addition to, rpc_object_set_type(). RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_object_set_inq_fn rpc_server_register_if 4 rpc_protseq_vector_free NAME rpc_protseq_vector_free - Frees the memory used by a vector and its protocol sequences Used by client or server applications. SYNOPSIS #include void rpc_protseq_vector_free( rpc_protseq_vector_t **protseq_vector, unsigned32 *status ); PARAMETERS Input/Output protseq_vector Specifies the address of a pointer to a vector of protocol sequences. On return the pointer is set to NULL. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status code and its meaning is as follows: rpc_s_ok Success. DESCRIPTION The rpc_protseq_vector_free() routine frees the memory used to store a vector of protocol sequences. The freed memory includes both the protocol sequences and the vector itself. Call rpc_network_inq_protseqs() to obtain a vector of protocol sequences. Follow a call to rpc_network_inq_protseqs() with a call to rpc_protseq_vector_free(). RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_network_inq_protseqs 4 rpc_rgy_get_codesets NAME rpc_rgy_get_codesets - Gets supported code sets information from the local host Used by client and server applications. SYNOPSIS #include void rpc_rgy_get_codesets( rpc_codeset_mgmt_p_t *code_sets_array, error_status_t *status ); PARAMETERS Input No input is required. Output code_sets_array An integer array that specifies the code sets that the client's or server's host environment supports. Each array element is an integer value that uniquely identifies one code set. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: dce_cs_c_cannot_open_file dce_cs_c_cannot_read_file rpc_s_ok rpc_s_no_memory DESCRIPTION The rpc_rgy_get_codesets() routine belongs to a set of DCE RPC routines for use by client and server applications that are transferring international character data in a heterogeneous character set and code sets environment. The rpc_rgy_get_codesets() routine examines the locale environment of the host on which the client or server process is running to determine the local code set currently in use by the client or server process and the set of supported code set conversion routines that exist on the host into which the client or server process can convert if necessary. It then reads the code sets registry on the local host to retrieve the unique identifiers associated with these supported code sets. The routine returns a code sets array. The set of values returned in this structure correspond to the process's local code set and the code sets into which processes that run on this host can convert. The array also contains, for each code set, the maximum number of bytes that code set uses to encode one character (c_max_bytes). Server applications use the rpc_rgy_get_codesets() routine in their initialization code to get their host's supported character and code sets values in order to export them into the name service database with rpc_ns_mgmt_set_attribute(). Client applications use the rpc_rgy_get_codesets() routine during the server binding selection process to retrieve the supported character and code sets at their host in order to evaluate them against the character and code sets that a server supports. Client applications that use the evaluation routines rpc_cs_eval_with_universal() and rpc_cs_eval_without_universal() do not need to call this routine explicitly, because these code sets evaluation routines call it on the client's behalf. Application developers who are writing their own character and code set evaluation routines may need to include rpc_rgy_get_codesets() in their user-written evaluation routines. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Commands: csrc(8dce). Functions: rpc_ns_mgmt_read_codesets rpc_ns_mgmt_remove_attribute rpc_ns_mgmt_set_attribute 4 rpc_rgy_get_max_bytes NAME rpc_rgy_get_max_bytes - Gets the maximum number of bytes that a code set uses to encode one character from the code set registry on a host Used by client and server applications. SYNOPSIS #include void rpc_rgy_get_max_bytes( unsigned32 rgy_code_set_value, unsigned16 *rgy_max_bytes, error_status_t *status ); PARAMETERS Input rgy_code_set_value The registered hexadecimal value that uniquely identifies the code set. Output rgy_max_bytes The registered decimal value that indicates the number of bytes this code set uses to encode one character. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: dce_cs_c_cannot_open_file dce_cs_c_cannot_read_file dce_cs_c_notfound dce_cs_c_unknown rpc_s_ok DESCRIPTION The rpc_rgy_get_max_bytes() routine belongs to a set of DCE RPC routines for use by client and server applications that are transferring international character data in a heterogeneous character set and code sets environment. The rpc_rgy_get_max_bytes() routine reads the code set registry on the local host. It takes the specified registered code set value, uses it as an index into the registry, and returns the decimal value that indicates the number of bytes that the code set uses to encode one character. The DCE RPC stub support routines for buffer sizing use the rpc_rgy_get_max_bytes() routine as part of their procedure to determine whether additional storage needs to be allocated for conversion between local and network code sets. The DCE RPC stub support routines call the rpc_rgy_get_max_bytes() routine once to get the rgy_max_bytes value for the code set to be used to transfer the data over the network (the "network" code set) then call the routine again to get the rgy_max_bytes value of their local code set. The stubs then compare the two values to determine whether or not additional buffers are necessary or whether the conversion can be done "in place". Client and server applications that use the DCE RPC buffer sizing routines byte_net_size(), byte_local_size(), wchar_t_net_size(), and wchar_t_local_size() do not need to call this routine explicitly because these DCE RPC stub support routines call it on their behalf. Application programmers who are developing their own stub support routines for buffer sizing can use the rpc_rgy_get_max_bytes() routine in their code to get code set max_byte information for their user- written buffer sizing routines. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Commands: csrc. Functions: dce_cs_loc_to_rgy dce_cs_rgy_to_loc rpc_ns_mgmt_read_code_sets rpc_rgy_get_code_sets 4 rpc_server_inq_bindings NAME rpc_server_inq_bindings - Returns binding handles for communications with a server Used by server applications. SYNOPSIS #include void rpc_server_inq_bindings( rpc_binding_vector_t **binding_vector, unsigned32 *status ); PARAMETERS Input None. Output binding_vector Returns the address of a vector of server binding handles. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_no_bindings No bindings. DESCRIPTION The rpc_server_inq_bindings() routine obtains a vector of server binding handles. Binding handles are created by the RPC runtime when a server application calls any of the following routines to register protocol sequences: + rpc_server_use_all_protseqs() + rpc_server_use_all_protseqs_if() + rpc_server_use_protseq() + rpc_server_use_protseq_ep() + rpc_server_use_protseq_if() The returned binding vector can contain binding handles with dynamic endpoints and binding handles with well-known endpoints, depending on which of the preceding routines the server application called. The rpc_intro reference page contains an explanation of dynamic and well- known endpoints. A server uses the vector of binding handles for exporting to the name service, for registering with the local endpoint map, or for conversion to string bindings. If there are no binding handles (no registered protocol sequences), this routine returns the rpc_s_no_bindings status code and returns the value NULL to the binding_vector parameter. The server is responsible for calling the rpc_binding_vector_free() routine to deallocate the memory used by the vector. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_vector_free rpc_ep_register rpc_ep_register_no_replace rpc_ns_binding_export rpc_server_use_all_protseqs rpc_server_use_all_protseqs_if rpc_server_use_protseq rpc_server_use_protseq_ep rpc_server_use_protseq_if 4 rpc_server_inq_if NAME rpc_server_inq_if - Returns the manager entry point vector registered for an interface Used by server applications. SYNOPSIS #include void rpc_server_inq_if( rpc_if_handle_t if_handle, uuid_t *mgr_type_uuid, rpc_mgr_epv_t *mgr_epv, unsigned32 *status ); PARAMETERS Input if_handle Specifies the interface specification whose manager Entry Point Vector (EPV) pointer is returned in the mgr_epv parameter. mgr_type_uuid Specifies a type UUID for the manager whose EPV pointer is returned in the mgr_epv parameter. Specifying the value NULL (or a nil UUID) has this routine return a pointer to the manager EPV that is registered with if_handle and the nil type UUID of the manager. Output mgr_epv Returns a pointer to the manager EPV corresponding to if_handle and mgr_type_uuid. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_unknown_if Unknown interface. rpc_s_unknown_mgr_type Unknown manager type. DESCRIPTION A server application calls the rpc_server_inq_if() routine to determine the manager EPV for a registered interface and type UUID of the manager. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_server_register_if 4 rpc_server_listen NAME rpc_server_listen - Tells the RPC runtime to listen for remote procedure calls Used by server applications. SYNOPSIS #include void rpc_server_listen( unsigned32 max_calls_exec, unsigned32 *status ); PARAMETERS Input max_calls_exec Specifies the maximum number of concurrent executing remote procedure calls. Use the value rpc_c_listen_max_calls_default to specify the default value. Also, the five rpc_server_use_*protseq* routines limit (according to their max_call_requests parameter) the number of concurrent remote procedure call requests that a server can accept. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_already_listening Server already listening. rpc_s_max_calls_too_small Maximum calls value too small. rpc_s_no_protseqs_registered No protocol sequences registered. DESCRIPTION The rpc_server_listen() routine makes a server listen for remote procedure calls. DCE RPC allows a server to simultaneously process multiple calls. The max_calls_exec parameter specifies the maximum number of concurrent remote procedure calls the server executes. Each remote procedure call executes in a call execution thread. The implementation of the RPC architecture determines whether it reuses call execution threads for the execution of subsequent remote procedure calls or, instead, it creates a new thread for each execution of a subsequent remote procedure call. The following conditions affect the number of concurrent remote procedure calls that a server can process: + Sufficient network resources must be available to accept simultaneous call requests arriving over a particular protocol sequence. The value of max_call_requests in the five rpc_server_use_*protseq* routines advises the RPC runtime about the runtime's request of network resources. + Enough call threads must be available to execute the simultaneous call requests once they have been accepted. The value of max_calls_exec in rpc_server_listen() specifies the number of call threads. These conditions are independent of each other. A server application that specifies a value for max_calls_exec greater than 1 is responsible for concurrency control among the remote procedures since each executes in a separate thread. If the server receives more remote procedure calls than it can execute (more calls than the value of max_calls_exec), the RPC runtime accepts and queues additional remote procedure calls until a call execution thread is available. From the client's perspective, a queued remote procedure call appears the same as one that the server is actively executing. A client call remains blocked and in the queue until any one of the following events occurs: + The remote procedure call is assigned to an available call execution thread and the call runs to completion. + The client no longer can communicate with the server. + The client thread is canceled and the remote procedure call does not complete within the cancel time-out limits. The implementation of the RPC architecture determines the amount of queuing it provides. The RPC runtime continues listening for remote procedure calls (that is, the routine does not return to the server) until one of the following events occurs: + One of the server application's manager routines calls rpc_mgmt_stop_server_listening(). + A client is allowed to, and makes, a remote rpc_mgmt_stop_server_listening() call to the server. On receiving a request to stop listening, the RPC runtime stops accepting new remote procedure calls for all registered interfaces. Executing calls and existing queued calls are allowed to complete. After all calls complete, rpc_server_listen() returns to the caller, which is a server application. For more information about a server's listening for and handling incoming remote procedure calls, refer to the OSF DCE Application Development Guide. It also contains information about canceled threads. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_mgmt_server_stop_listening rpc_server_register_if rpc_server_use_all_protseqs rpc_server_use_all_protseqs_if rpc_server_use_protseq rpc_server_use_protseq_ep rpc_server_use_protseq_if Books: OSF DCE Application Development Guide. 4 rpc_server_register_auth_info NAME rpc_server_register_auth_info - Registers authentication information with the RPC runtime Used by server applications. SYNOPSIS #include void rpc_server_register_auth_info( unsigned_char_t *server_princ_name, unsigned32 authn_svc, rpc_auth_key_retrieval_fn_t get_key_fn, void *arg, unsigned32 *status ); PARAMETERS Input server_princ_name Specifies the principal name to use for the server when authenticating remote procedure calls using the service specified by authn_svc. The content of the name and its syntax is defined by the authentication service in use. authn_svc Specifies the authentication service to use when the server receives a remote procedure call request. The following authentication services are supported: rpc_c_authn_none No authentication. rpc_c_authn_dce_secret DCE shared-secret key authentication. rpc_c_authn_winnt Microsoft NT Lan Manager authentication. rpc_c_authn_dce_public DCE public key authentication (reserved for future use). rpc_c_authn_default DCE default authentication service. get_key_fn Specifies the address of a server-provided routine that returns encryption keys. The following C definition for rpc_auth_key_retrieval_fn_t illustrates the prototype for the encryption key acquisition routine: typedef void (*rpc_auth_key_retrieval_fn_t) ( void *arg, /* in */ unsigned_char_t *server_princ_name, /* in */ unsigned32 key_type, /* in */ unsigned32 key_ver, /* in */ void **key, /* out */ unsigned32 *status /* out */ ); The RPC runtime passes the server_princ_name parameter value specified on the call to rpc_server_register_auth_info(), as the server_princ_name parameter value, to the get_key_fn key acquisition routine. The RPC runtime automatically provides a value for the key version (key_ver) parameter. For a key_ver value of 0 (zero), the key acquisition routine must return the most recent key available. The routine returns the key in the key parameter. The key_type parameter specifies a Kerberos encryption key type. Because currently the DCE supports only DES encryption, this parameter can be ignored. If the key acquisition routine, when called from the rpc_server_register_auth_info() routine, returns a status other than rpc_s_ok, the rpc_server_register_auth_info() routine fails and returns the error status to the calling server. If the key acquisition routine, when called by the RPC runtime while authenticating a client remote procedure call request, returns a status other than rpc_s_ok, the request fails and the RPC runtime returns the error status to the client. arg Specifies an argument to pass to the get_key_fn key acquisition routine, if specified. (See the description of the get_key_fn parameter for details.) Specify NULL for arg to use the default key table file, DCE$LOCAL:[KRB]v5srvtab.; The calling server must be privileged to access this file. If arg is a key table file name, the file must have been created with the ktadd command. If the specified key table file resides in DCE$LOCAL:[KRB5], you can supply only the file name. If the file does not reside in DCE$LOCAL:[KRB5], you must supply the full pathname. You must prepend the file's absolute pathname with the prefix FILE:. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_unknown_authn_service Unknown authentication service. rpc_s_key_func_not_allowed authn_svc is rpc_c_authn_default and a non-null value was supplied for get_key_fn parameter. DESCRIPTION The rpc_server_register_auth_info() routine registers an authenti- cation service to use for authenticating remote procedure calls to a particular server principal. A server calls this routine once for each authentication service and principal name combination that it wants to register. The authentication service specified by a client (using the rpc_binding_set_auth_info() routine) must be one of the authentication services registered by the server. If it is not, the client's remote procedure call request fails with an rpc_s_unknown_authn_service status code. The following table shows the RPC runtime behavior for acquiring encryption keys for each supported authentication service. Note that if authn_svc is rpc_c_authn_default, then get_key_fn must be NULL. RPC Key Acquisition for Authentication Services _______________________________________________________________________ authn_svc get_key_fn arg Runtime Behavior _______________________________________________________________________ rpc_c_authn_default NULL NULL Uses the default method of encryption key acquisition from the default key table. _______________________________________________________________________ rpc_c_authn_default NULL non-NULL Uses the default method of encryption key acquisition from the specified key table. _______________________________________________________________________ rpc_c_authn_default non-NULL Ignored Error returned. _______________________________________________________________________ rpc_c_authn_none Ignored Ignored No authentication performed. _______________________________________________________________________ rpc_c_authn_dce_secret NULL NULL Uses the default method of encryption key acquisition from the default key table. _______________________________________________________________________ rpc_c_authn_dce_secret NULL non-NULL Uses the default method of encryption key acquisition from the specified key table. _______________________________________________________________________ rpc_c_authn_dce_secret non-NULL NULL Uses the specified encryp- tion key acquisition routine to obtain keys from the default key table. _______________________________________________________________________ rpc_c_authn_dce_secret non-NULL non-NULL Uses the specified encryp- tion key acquisition routine to obtain keys from the specified key table. _______________________________________________________________________ rpc_c_authn_winnt Ignored Ignored Uses the default method of encryption key acquisition from the default key table. _______________________________________________________________________ rpc_c_authn_dce_public Ignored Ignored (Reserved for future use.) RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_set_auth_info 4 rpc_server_register_if NAME rpc_server_register_if - Registers an interface with the RPC runtime Used by server applications. SYNOPSIS #include void rpc_server_register_if( rpc_if_handle_t if_handle, uuid_t *mgr_type_uuid, rpc_mgr_epv_t mgr_epv, unsigned32 *status ); PARAMETERS Input if_handle An IDL-generated data structure specifying the interface to register. mgr_type_uuid Specifies a type UUID to associate with the mgr_epv parameter. Specifying the value NULL (or a nil UUID) registers the if_handle with a nil type UUID. mgr_epv Specifies the manager routines' entry point vector. To use the IDL-generated default entry point vector, specify NULL. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_type_already_registered An interface with the given type of UUID is already registered. DESCRIPTION The rpc_server_register_if() routine registers a server interface with the RPC runtime. A server can register an unlimited number of interfaces. Once registered, an interface is available to clients through any binding handle of the server, provided that the binding handle is compatible for the client. A server must provide the following information to register an interface: + An interface specification, which is a data structure generated by the IDL compiler. The server specifies the interface specification of the interface using the if_handle parameter. + A type UUID and manager Entry Point Vector (EPV), a data pair that determines which manager routine executes when a server receives a remote procedure call request from a client. The server specifies the type UUID and EPV using the mgr_type_uuid and mgr_epv parameters, respectively. Note that when a non-nil type UUID is specified, the server must also call the rpc_object_set_type() routine to register objects of this non-nil type. A server that only offers a single manager for an interface calls rpc_server_register_if() once for that interface. In the simple case where the single manager's entry point names are the same as the operation names in the IDL interface definition, the IDL-generated default manager EPV for the interface may be used. The value NULL in mgr_epv specifies the default manager EPV. Note that if a server offers multiple implementations of an interface, the server code must register a separate manager entry point vector for each interface implementation. Rules for Invoking Manager Routines The RPC runtime dispatches an incoming remote procedure call to a manager that offers the requested RPC interface. When multiple managers are registered for an interface, the RPC runtime must select one of them. To select a manager, the RPC runtime uses the object UUID specified by the call's binding handle. The following table summarizes the rules applied for invoking manager routines. Rules for Invoking Manager Routines _______________________________________________________________________ Object Has Server Has Server UUID Set Type of Set Type for of Call¹ Object UUID?² Manager EPV³ Dispatching Action _______________________________________________________________________ Nil Not applicable(4) Yes Uses the manager with the nil type UUID. Nil Not applicable(4) No Error (rpc_s_unknown_mgr_type). Rejects the remote procedure call. Non-nil Yes Yes Uses the manager with the same type UUID. Non-nil No Ignored Uses the manager with the nil type UUID. If no manager with the nil type UUID, error (rpc_s_unknown_mgr_type). Rejects the remote procedure call. Non-nil Yes No Error (rpc_s_unknown_mgr_type). Rejects the remote procedure call. ¹ This is the object UUID found in a binding handle for a remote procedure. ² By calling rpc_object_set_type() to specify the type UUID for an object. ³ By calling rpc_server_register_if() using the same type UUID. 4 The nil object UUID is always automatically assigned the nil type UUID. It is illegal to specify a nil object UUID in rpc_object_set_type(). For more information about registering server interfaces and invoking manager routines, refer to the OSF DCE Application Development Guide. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_set_object rpc_ep_register rpc_ep_register_no_replace rpc_ns_binding_export rpc_object_set_type rpc_server_unregister_if Books: OSF DCE Application Development Guide. 4 rpc_server_unregister_if NAME rpc_server_unregister_if - Removes an interface from the RPC runtime Used by server applications. SYNOPSIS #include void rpc_server_unregister_if( rpc_if_handle_t if_handle, uuid_t *mgr_type_uuid, unsigned32 *status ); PARAMETERS Input if_handle Specifies an interface specification to unregister (remove). Specify NULL to remove all interfaces previously registered with the type UUID value given in the mgr_type_uuid parameter. mgr_type_uuid Specifies the type UUID for the manager Entry Point Vector (EPV) to remove. This needs to be the same value as provided in a call to the rpc_server_register_if() routine. Specify NULL to remove the interface given in the if_handle parameter for all previously registered type UUIDs. Specify a nil UUID to remove the IDL-generated default manager EPV. In this case all manager EPVs registered with a non-nil type UUID remain registered. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_unknown_if Unknown interface. rpc_s_unknown_mgr_type Unknown manager type. DESCRIPTION The rpc_server_unregister_if() routine removes the association between an interface and a manager Entry Point Vector (EPV). Specify the manager EPV to remove by providing, in the mgr_type_uuid parameter, the type UUID value specified in a call to the rpc_server_register_if() routine. Once removed, an interface is no longer available to client applications. When an interface is removed, the RPC runtime stops accepting new calls for that interface. Executing calls (on that interface) are allowed to complete. The table below summarizes the actions of this routine. Rules for Removing an Interface _____________________________________________________________________ if_handle mgr_type_uuid Action _____________________________________________________________________ non-NULL non-NULL Removes the manager EPV associated with the specified parameters. non-NULL NULL Removes all manager EPVs associated with parameter if_handle. NULL non-NULL Removes all manager EPVs associated with parameter mgr_type_uuid. NULL NULL Removes all manager EPVs. Note that when both of the parameters if_handle and mgr_type_uuid are given the value NULL, this call has the effect of preventing the server from receiving any new remote procedure calls since all the manager EPVs for all interfaces have been removed. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_server_register_if 4 rpc_server_use_all_protseqs NAME rpc_server_use_all_protseqs - Tells the RPC runtime to use all supported protocol sequences for receiving remote procedure calls Used by server applications. SYNOPSIS #include void rpc_server_use_all_protseqs( unsigned32 max_call_requests, unsigned32 *status ); PARAMETERS Input max_call_requests Specifies the maximum number of concurrent remote procedure call requests that the server can accept. The RPC runtime guarantees that the server can accept at least this number of concurrent call requests. The actual number of these requests can be greater than the value of max_call_requests and can vary for each protocol sequence. Use the value rpc_c_protseq_max_reqs_default to specify the default parameter value. Note that in this version of DCE RPC, any number you specify is replaced by the default value. Also, the rpc_server_listen() routine limits (according to its max_calls_exec parameter) the amount of concurrent remote procedure call execution. See the rpc_server_listen reference page for more information. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_cant_create_socket Cannot create socket. rpc_s_max_descs_exceeded Exceeded maximum number of network descriptors. rpc_s_no_protseqs No supported protocol sequences. DESCRIPTION The rpc_server_use_all_protseqs() routine registers all supported protocol sequences with the RPC runtime. A server must register at least one protocol sequence with the RPC runtime to receive remote procedure call requests. For each protocol sequence registered by a server, the RPC runtime creates one or more binding handles. Each binding handle contains a dynamic endpoint that the RPC runtime and operating system generated. The max_call_requests parameter allows you to specify the maximum number of concurrent remote procedure call requests the server handles. After registering protocol sequences, a server typically calls the following routines: rpc_server_inq_bindings() Obtains a vector containing all of the server's binding handles. rpc_ep_register() Registers the binding handles with the local endpoint map. rpc_ep_register_no_replace() Registers the binding handles with the local endpoint map. rpc_ns_binding_export() Places the binding handles in the name service database for access by any client. rpc_binding_vector_free() Frees the vector of server binding handles. rpc_server_register_if() Registers with the RPC runtime those interfaces that the server offers. rpc_server_listen() Enables the reception of remote procedure calls. To register protocol sequences selectively, a server calls one of the following routines: rpc_server_use_protseq() rpc_server_use_all_protseqs_if() rpc_server_use_protseq_if() rpc_server_use_protseq_ep() For an explanation of how a server can establish a client/server relationship without using the local endpoint map or the name service database, see the information on string bindings in the rpc_intro reference page. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_from_string_binding rpc_binding_to_string_binding rpc_binding_vector_free rpc_ep_register rpc_ep_register_no_replace rpc_ns_binding_export rpc_server_inq_bindings rpc_server_listen rpc_server_register_if rpc_server_use_all_protseqs_if rpc_server_use_protseq rpc_server_use_protseq_ep rpc_server_use_protseq_if 4 rpc_server_use_all_protseqs_if NAME rpc_server_use_all_protseqs_if - Tells the RPC runtime to use all the protocol sequences and endpoints specified in the interface specification for receiving remote procedure calls Used by server applications. SYNOPSIS #include void rpc_server_use_all_protseqs_if( unsigned32 max_call_requests, rpc_if_handle_t if_handle, unsigned32 *status ); PARAMETERS Input max_call_requests Specifies the maximum number of concurrent remote procedure call requests that the server can accept. The RPC runtime guarantees that the server can accept at least this number of concurrent call requests. The actual number of these requests can be greater that the value of max_call_requests and can vary for each protocol sequence. Use the value rpc_c_protseq_max_reqs_default to specify the default parameter value. Note that in this version of DCE RPC, any number you specify is replaced by the default value. Also, the rpc_server_listen() routine limits (according to its max_calls_exec parameter) the amount of concurrent remote procedure call execution. See the rpc_server_listen reference page for more information. if_handle Specifies an interface specification containing the protocol sequences and their corresponding endpoint information to use in creating binding handles. Each created binding handle contains a well-known (non-dynamic) endpoint contained in the interface specification. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_calls_too_large_for_wk_ep Maximum concurrent calls too large. rpc_s_cant_bind_socket Cannot bind to socket. rpc_s_cant_create_socket Cannot create socket. rpc_s_cant_inq_socket Cannot inquire endpoint from socket. rpc_s_invalid_endpoint_format Invalid interface handle. rpc_s_max_descs_exceeded Exceeded maximum number of network descriptors. rpc_s_no_protseqs No supported protocol sequences. DESCRIPTION The rpc_server_use_all_protseqs_if() routine registers all protocol sequences and associated endpoint address information provided in the IDL file with the RPC runtime. A server must register at least one protocol sequence with the RPC runtime to receive remote procedure call requests. For each protocol sequence registered by a server, the RPC runtime creates one or more binding handles. Each binding handle contains the well-known endpoint specified in the IDL file. The max_call_requests parameter allows you to specify the maximum number of concurrent remote procedure call requests the server handles. If you want to register selected protocol sequences specified in the IDL, your server uses rpc_server_use_protseq_if(). The explanation of rpc_server_use_all_protseqs() contains a list of the routines a server typically calls after calling this routine. (However, a server that uses only rpc_server_use_all_protseqs_if() does not subsequently call rpc_ep_register() or rpc_ep_register_no_replace().) For an explanation of how a server can establish a client/server relationship without using the local endpoint map or the name service database, see the information on string bindings in the rpc_intro reference page. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_vector_free rpc_ep_register rpc_ep_register_no_replace rpc_ns_binding_export rpc_server_inq_bindings rpc_server_listen rpc_server_register_if rpc_server_use_all_protseqs rpc_server_use_protseq rpc_server_use_protseq_ep rpc_server_use_protseq_if 4 rpc_server_use_protseq NAME rpc_server_use_protseq - Tells the RPC runtime to use the specified protocol sequence for receiving remote procedure calls Used by server applications. SYNOPSIS #include void rpc_server_use_protseq( unsigned_char_t *protseq, unsigned32 max_call_requests, unsigned32 *status ); PARAMETERS Input protseq Specifies a string identifier for the protocol sequence to register with the RPC runtime. (For a list of string identifiers, see the table of valid protocol sequences in the rpc_intro(3rpc) reference page.) max_call_requests Specifies the maximum number of concurrent remote procedure call requests that the server can accept. The RPC runtime guarantees that the server can accept at least this number of concurrent call requests. The actual number of these requests can be greater than the value of max_call_requests and can vary for each protocol sequence. Use the value rpc_c_protseq_max_reqs_default to specify the default parameter value. Note that in this version of DCE RPC, any number you specify is replaced by the default value. Also, rpc_server_listen() limits (according to its max_calls_exec parameter) the amount of concurrent remote procedure call execution. See the rpc_server_listen reference page for more information. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_cant_create_socket Cannot create socket. rpc_s_invalid_rpc_protseq Invalid protocol sequence. rpc_s_max_descs_exceeded Exceeded maximum number of network descriptors. rpc_s_protseq_not_supported Protocol sequence not supported on this host. DESCRIPTION The rpc_server_use_protseq() routine registers a single protocol sequence with the RPC runtime. A server must register at least one protocol sequence with the RPC runtime to receive remote procedure call requests. A server can call this routine multiple times to register additional protocol sequences. For each protocol sequence registered by a server, the RPC runtime creates one or more binding handles. Each binding handle contains a dynamic endpoint that the RPC runtime and operating system generated. The max_call_requests parameter allows you to specify the maximum number of concurrent remote procedure call requests the server handles. A server calls rpc_server_use_all_protseqs() to register all protocol sequences. The explanation of the rpc_server_use_all_protseqs() routine contains a list of the routines a server typically calls after calling this routine. For an explanation of how a server can establish a client/server relationship without using the local endpoint map or the name service database, see the information on string bindings in the rpc_intro reference page. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_vector_free rpc_ep_register rpc_ep_register_no_replace rpc_network_is_protseq_valid rpc_ns_binding_export rpc_server_inq_bindings rpc_server_listen rpc_server_register_if rpc_server_use_all_protseqs rpc_server_use_all_protseqs_if rpc_server_use_protseq_ep rpc_server_use_protseq_if 4 rpc_server_use_protseq_ep NAME rpc_server_use_protseq_ep - Tells the RPC runtime to use the specified protocol sequence combined with the specified endpoint for receiving remote procedure calls Used by server applications. SYNOPSIS #include void rpc_server_use_protseq_ep( unsigned_char_t *protseq, unsigned32 max_call_requests, unsigned_char_t *endpoint, unsigned32 *status ); PARAMETERS Input protseq Specifies a string identifier for the protocol sequence to register with the RPC runtime. (For a list of string identifiers, see the table of valid protocol sequences in the rpc_intro(3rpc) reference page. max_call_requests Specifies the maximum number of concurrent remote procedure call requests that the server can accept. The RPC runtime guarantees that the server can accept at least this number of concurrent call requests. The actual number of these requests can be greater than the value of max_call_requests and can vary for each protocol sequence. Use the value rpc_c_protseq_max_reqs_default to specify the default parameter value. Note that in this version of DCE RPC, any number you specify is replaced by the default value. Also, rpc_server_listen() limits (according to its max_calls_exec parameter) the amount of concurrent remote procedure call execution. See the rpc_server_listen reference page for more information. endpoint Specifies address information for an endpoint. This information is used in creating a binding handle for the protocol sequence specified in the protseq parameter. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_calls_too_large_for_wk_ep Maximum concurrent calls too large. rpc_s_cant_bind_socket Cannot bind to socket. rpc_s_cant_create_socket Cannot create socket. rpc_s_invalid_endpoint_format Invalid endpoint format. rpc_s_invalid_rpc_protseq Invalid protocol sequence. rpc_s_max_descs_exceeded Exceeded maximum number of network descriptors. rpc_s_protseq_not_supported Protocol sequence not supported on this host. DESCRIPTION The rpc_server_use_protseq_ep() routine registers a protocol sequence and its specified endpoint address information with the RPC runtime. A server must register at least one protocol sequence with the RPC runtime to receive remote procedure call requests. A server can call this routine multiple times to register additional protocol sequences and endpoints. For each protocol sequence registered by a server, the RPC runtime creates one or more binding handles. Each binding handle contains the well-known endpoint specified in the endpoint parameter. The max_call_requests parameter allows you to specify the maximum number of concurrent remote procedure call requests the server handles. The explanation of rpc_server_use_all_protseqs() contains a list of the routines a server typically calls after calling this routine. For an explanation of how a server can establish a client/server relationship without using the local endpoint map or the name service database, see the information on string bindings in the rpc_intro reference page. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_vector_free rpc_ep_register rpc_ep_register_no_replace rpc_ns_binding_export rpc_server_inq_bindings rpc_server_listen rpc_server_register_if rpc_server_use_all_protseqs rpc_server_use_all_protseqs_if rpc_server_use_protseq rpc_server_use_protseq_ep 4 rpc_server_use_protseq_if NAME rpc_server_use_protseq_if - Tells the RPC runtime to use the specified protocol sequence combined with the endpoints in the interface specification for receiving remote procedure calls Used by server applications. SYNOPSIS #include void rpc_server_use_protseq_if( unsigned_char_t *protseq, unsigned32 max_call_requests, rpc_if_handle_t if_handle, unsigned32 *status ); PARAMETERS Input protseq Specifies a string identifier for the protocol sequence to register with the RPC runtime. For a list of string identifiers, see the table of valid protocol sequences in the rpc_intro(3rpc) reference page. max_call_requests Specifies the maximum number of concurrent remote procedure call requests that the server can accept. The RPC runtime guarantees that the server can accept at least this number of concurrent call requests. The actual number of these requests can be greater than the value of max_call_requests and can vary for each protocol sequence. Use the value rpc_c_protseq_max_reqs_default to specify the default parameter value. Note that in this version of DCE RPC, any number you specify is replaced by the default value. Also, the rpc_server_listen() routine limits (according to its max_calls_exec parameter) the amount of concurrent remote procedure call execution. See the rpc_server_listen reference page for more information. if_handle Specifies an interface specification whose endpoint information is used in creating a binding for the protocol sequence specified in the protseq parameter. Each created binding handle contains a well-known (nondynamic) endpoint contained in the interface specification. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_calls_too_large_for_wk_ep Maximum concurrent calls too large. rpc_s_cant_bind_socket Cannot bind to socket. rpc_s_invalid_endpoint_format Invalid endpoint format. rpc_s_invalid_rpc_protseq Invalid protocol sequence. rpc_s_max_descs_exceeded Exceeded maximum number of network descriptors. rpc_s_protseq_not_supported Protocol sequence not supported on this host. DESCRIPTION The rpc_server_use_protseq_if() routine registers one protocol sequence with the RPC runtime, including its endpoint address information as provided in the specified IDL file. A server must register at least one protocol sequence with the RPC runtime to receive remote procedure call requests. A server can call this routine multiple times to register additional protocol sequences. For each protocol sequence registered by a server, the RPC runtime creates one or more binding handles. Each binding handle contains the well-known endpoint specified in the IDL file. The max_call_requests parameter allows you to specify the maximum number of concurrent remote procedure call requests the server handles. To register all protocol sequences from the IDL, a server calls the rpc_server_use_all_protseqs_if() routine. The explanation of rpc_server_use_all_protseqs() contains a list of the routines a server typically calls after calling this routine. However, a server that uses only rpc_server_use_protseq_if() does not subsequently call rpc_ep_register() or rpc_ep_register_no_replace(). For an explanation of how a server can establish a client/server relationship without using the local endpoint map or the name service database, see the information on string bindings in the rpc_intro reference page. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_vector_free rpc_ep_register rpc_ep_register_no_replace rpc_ns_binding_export rpc_server_inq_bindings rpc_server_listen rpc_server_register_if rpc_server_use_all_protseqs rpc_server_use_all_protseqs_if rpc_server_use_protseq rpc_server_use_protseq_ep 4 rpc_set_local_float_drep Name: rpc_set_local_float_drep - Sets the float type in the runtime to the one with which the application is being compiled SYNOPSIS: #include void rpc_set_local_float_drep (unsigned8 float_drep, unsigned32 *status); PARAMETERS Input float_drep The parameter should always be passed as using the macro "RPC_APPLICATION_FLOAT_TYPE". This macro will be define to 0 or 1 based on the compilation option specified for the float type. Output status The routine will always return "rpc_s_ok" status. DESCRIPTION: The routine rpc_set_local_float_drep allows the RPC application to set the floating point type being used by the application Only G_FLOAT and IEEE_FLOAT floating types are supported. This routine if used,should be placed before any other API calls to the RPC runtime. The first parameter float_drep should be passed using the macro RPC_APPLICATION_FLOAT_TYPE that is defined in IDLBASE.H header file. This macro will be set to appropriate value based on the /FLOAT compilation option. This routine can be used only on Alpha and I64 and will not be supported on VAX. RETURN TYPE: No value is returned. 4 rpc_sm_allocate NAME rpc_sm_allocate - Allocates memory within the RPC stub memory management scheme SYNOPSIS #include idl_void_p_t rpc_sm_allocate ( unsigned long size, unsigned32 *status ); PARAMETERS Input size Specifies, in bytes, the size of memory to be allocated. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. Possible status codes and their meanings include: rpc_s_ok Success. DESCRIPTION Applications call rpc_sm_allocate to allocate memory within the RPC stub memory management scheme. Before a call to this routine, the stub memory management environment must have been established. For manager code that is called from the stub, the stub itself normally establishes the necessary environment. When rpc_sm_allocate is used by code that is not called from the stub, the application must establish the required memory management environment by calling rpc_sm_enable_allocate. When the stub establishes the memory management environment, the stub itself frees any memory allocated by rpc_sm_allocate. The application can free such memory before returning to the calling stub by calling rpc_sm_free. When the application establishes the memory management environment, it must free any memory allocated, either by calling rpc_sm_free or by calling rpc_sm_disable_allocate. Multiple threads may call rpc_sm_allocate and rpc_sm_free to manage the same memory within the stub memory management environment. To do so, the threads must share the same stub memory management thread handle. Applications pass thread handles from thread to thread by calling rpc_sm_get_thread_handle and rpc_sm_set_thread_handle. RETURN VALUES A pointer to the allocated memory. RELATED INFORMATION Functions: rpc_sm_free rpc_sm_enable_allocate rpc_sm_disable_allocate rpc_sm_get_thread_handle rpc_sm_set_thread_handle 4 rpc_sm_client_free NAME rpc_sm_client_free - Frees memory returned from a client stub SYNOPSIS #include void rpc_sm_client_free ( idl_void_p_t node_to_free, unsigned32 *status ); PARAMETERS Input node_to_free Specifies a pointer to memory returned from a client stub. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. Possible status codes and their meanings include: rpc_s_ok Success. DESCRIPTION The rpc_sm_client_free routine releases memory allocated and returned from a client stub. The thread calling rpc_sm_client_free must have the same thread handle as the thread that made the RPC call. Applications pass thread handles from thread to thread by calling rpc_sm_get_thread_handle and rpc_sm_set_thread_handle. This routine enables a routine to deallocate dynamically allocated memory returned by an RPC call without knowledge of the memory management environment from which it was called. RETURN VALUES None. RELATED INFORMATION Functions: rpc_sm_free rpc_sm_get_thread_handle rpc_sm_set_client_alloc_free rpc_sm_set_thread_handle rpc_sm_swap_client_alloc_free 4 rpc_sm_destroy_client_context NAME rpc_sm_destroy_client_context - Reclaims the client memory resources for a context handle, and sets the context handle to null SYNOPSIS #include void rpc_sm_destroy_client_context( idl_void_p_t p_unusable_context_handle, unsigned32 *status ); PARAMETERS Input p_unusable_context_handle Specifies the context handle that can no longer be accessed. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. Possible status codes and their meanings include: rpc_s_ok Success. DESCRIPTION The rpc_sm_destroy_client_context routine is used by client applications to reclaim the client resources used in maintaining an active context handle. Applications call this routine after a communications error makes the context handle unusable. When the rpc_sm_destroy_client_context routine reclaims the memory resources, it also sets the context handle to null. RETURN VALUES None. 4 rpc_sm_disable_allocate NAME rpc_sm_disable_allocate - Releases resources and allocated memory within the stub memory management scheme SYNOPSIS #include void rpc_sm_disable_allocate ( unsigned32 *status ); PARAMETERS Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. Possible status codes and their meanings include: rpc_s_ok Success. DESCRIPTION The rpc_sm_disable_allocate routine releases all resources acquired by a call to rpc_sm_enable_allocate, and any memory allocated by calls to rpc_sm_allocate after the call to rpc_sm_enable_allocate was made. The rpc_sm_enable_allocate and rpc_sm_disable_allocate routines must be used in matching pairs. RELATED INFORMATION Functions: rpc_sm_allocate rpc_sm_enable_allocate 4 rpc_sm_enable_allocate NAME rpc_sm_enable_allocate - Enables the stub memory managment environment SYNOPSIS #include void rpc_sm_enable_allocate( unsigned32 *status ); PARAMETERS Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. Possible status codes and their meanings include: rpc_s_ok Success. DESCRIPTION Applications can call rpc_sm_enable_allocate to establish a stub memory management environment in cases where one is not established by the stub itself. A stub memory management environment must be established before any calls are made to rpc_sm_allocate. For server manager code called from the stub, the stub memory management environment is normally established by the stub itself. Code that is called from other contexts needs to call rpc_sm_enable_allocate before calling rpc_sm_allocate. For a discussion of how spawned threads acquire a stub memory management environment, see the rpc_sm_get_thread_handle and rpc_sm_set_thread_handle reference pages. RETURN VALUES None RELATED INFORMATION Functions: rpc_sm_allocate rpc_sm_disable_allocate 4 rpc_sm_free NAME rpc_sm_free - Frees memory allocated by the rpc_sm_allocate routine SYNOPSIS #include void rpc_sm_free ( idl_void_p_t node_to_free, unsigned32 *status ); PARAMETERS Input node_to_free Specifies a pointer to memory allocated by rpc_sm_allocate. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. Possible status codes and their meanings include: rpc_s_ok Success. DESCRIPTION Applications call rpc_sm_free to release memory allocated by rpc_sm_allocate. When the stub allocates memory within the stub memory management environment, manager code called from the stub can also use rpc_sm_free to release memory allocated by the stub. The thread calling rpc_sm_free must have the same thread handle as the thread that allocated the memory with rpc_sm_allocate. Applications pass thread handles from thread to thread by calling rpc_sm_get_thread_handle and rpc_sm_set_thread_handle. RETURN VALUES None. RELATED INFORMATION Functions: rpc_sm_allocate rpc_sm_get_thread_handle rpc_sm_set_thread_handle 4 rpc_sm_get_thread_handle NAME rpc_sm_get_thread_handle - Gets a thread handle for the stub memory management environment SYNOPSIS #include rpc_sm_thread_handle_t rpc_sm_get_thread_handle( unsigned32 *status ); PARAMETERS Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. Possible status codes and their meanings include: rpc_s_ok Success. DESCRIPTION Applications call rpc_sm_get_thread_handle to get a thread handle for the current stub memory management environment. A thread that is managing memory within the stub memory managment scheme calls pc_sm_get_thread_handle to get a thread handle for its current stub memory management environment. A thread that calls rpc_sm_set_thread_handle with this handle, is able to use the same memory management environment. When multiple threads call rpc_sm_allocate and rpc_sm_free to manage the same memory, they must share the same thread handle. The thread that established the stub memory management environment calls rpc_sm_get_thread_handle to get a thread handle before spawning new threads that will manage the same memory. The spawned threads then call rpc_sm_set_thread_handle with the handle provided by the parent thread. Typically, rpc_sm_get_thread_handle is called by a server manager routine before it spawns additional threads. Normally the stub sets up the memory management environment for the manager routine. The manager calls rpc_sm_get_thread_handle to make this environment available to the spawned threads. A thread may also use rpc_sm_get_thread_handle and rpc_sm_set_thread_handle to save and restore its memory management environment. RETURN VALUES A thread handle. RELATED INFORMATION Functions: rpc_sm_allocate rpc_sm_free rpc_sm_set_thread_handle 4 rpc_sm_set_client_alloc_free NAME rpc_sm_set_client_alloc_free - Sets the memory allocation and freeing mechanisms used by the client stubs SYNOPSIS #include void rpc_sm_set_client_alloc_free ( idl_void_p_t (*p_allocate) (unsigned long size), void (*p_free) (idl_void_p_t ptr), unsigned32 *status ); PARAMETERS Input p_allocate Specifies a memory allocator routine. p_free Specifies a memory free routine. This routine is used to free memory allocated with the routine specified by p_allocate. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. Possible status codes and their meanings include: rpc_s_ok Success. DESCRIPTION The rpc_sm_set_client_alloc_free routine overrides the default routines that the client stub uses to manage memory. The default memory management routines are ISO malloc and ISO free except when the remote call occurs within manager code in which case the default memory management routines are rpc_sm_allocate and rpc_sm_free. RETURN VALUES None. RELATED INFORMATION Functions: rpc_sm_allocate rpc_sm_free 4 rpc_sm_set_thread_handle NAME rpc_sm_set_thread_handle - Sets a thread handle for the stub memory management environment SYNOPSIS #include void rpc_sm_set_thread_handle ( rpc_sm_thread_handle_t id, unsigned32 *status ); PARAMETERS Input id Specifies a thread handle returned by a call to rpc_sm_get_thread_handle. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. Possible status codes and their meanings include: rpc_s_ok Success. DESCRIPTION An application thread calls rpc_sm_set_thread_handle to set a thread handle for memory management within the stub memory management environment. A thread that is managing memory within the stub memory managment scheme calls rpc_sm_get_thread_handle to get a thread handle for its current stub memory management environment. A thread that calls rpc_sm_set_thread_handle with this handle is able to use the same memory management environment. When multiple threads call rpc_sm_allocate and rpc_sm_free to manage the same memory, they must share the same thread handle. The thread that established the stub memory management environment calls rpc_sm_get_thread_handle to get a thread handle before spawning new threads that will manage the same memory. The spawned threads then call rpc_sm_set_thread_handle with the handle provided by the parent thread. Typically, rpc_sm_set_thread_handle is called by a thread spawned by a server manager routine. Normally the stub sets up the memory management environment for the manager routine and the manager calls rpc_sm_get_thread_handle to get a thread handle. Each spawned thread then calls rpc_sm_get_thread_handle to get access to the manager's memory management environment. A thread may also use rpc_sm_get_thread_handle and rpc_sm_set_thread_handle to save and restore its memory management environment. RETURN VALUES RELATED INFORMATION Functions: rpc_sm_get_thread_handle rpc_sm_allocate rpc_sm_free 4 rpc_sm_swap_client_alloc_free NAME rpc_sm_swap_client_alloc_free - Exchanges the current memory allocation and freeing mechanism used by the client stubs with one supplied by the client SYNOPSIS #include void rpc_sm_swap_client_alloc_free ( idl_void_p_t (*p_allocate) (unsigned long size), void (*p_free) (idl_void_p_t ptr), idl_void_p_t (**p_p_old_allocate) (unsigned long size), void (**p_p_old_free) (idl_void_p_t ptr), unsigned32 *status ); PARAMETERS Input p_allocate Specifies a new memory allocation routine. p_free Specifies a new memory free routine. Output p_p_old_allocate Returns the memory allocation routine in use before the call to this routine. p_p_old_free Returns the memory free routine in use before the call to this routine. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. Possible status codes and their meanings include: rpc_s_ok Success. DESCRIPTION The rpc_sm_swap_client_alloc_free routine exchanges the current allocate and free mechanisms used by the client stubs for routines supplied by the caller. RETURN VALUES None. RELATED INFORMATION Functions: rpc_sm_allocate rpc_sm_free rpc_sm_set_client_alloc_free 4 rpc_ss_allocate NAME rpc_ss_allocate - Allocates memory within the RPC stub memory management scheme Used by server or possibly by client applications. SYNOPSIS #include idl_void_p_t rpc_ss_allocate( idl_size_t size ); PARAMETERS Input size Specifies, in bytes, the size of memory to be allocated. Note that in ANSI standard C environments, idl_void_p_t is defined as void * and in other environments is defined as char *. DESCRIPTION Usually, the rpc_ss_allocate() routine is used in the manager code that is called from a server stub. Memory allocated by rpc_ss_allocate is released by the server stub after marshalling any output parameters at the end of the remote call in which the memory was allocated. If you want to release memory allocated by rpc_ss_allocate() before returning from the manager code use rpc_ss_free(). You can also use rpc_ss_free() in manager code to release memory pointed to by a full pointer (ptr) in an input parameter. When the server uses rpc_ss_allocate(), the server stub creates the environment the routine needs. If the parameters of the operation include any pointers other than those used for passing parameters by reference, the environment is set up automatically. If you need to use rpc_ss_allocate() in a manager code routine that does not have a pointer in any of its parameters, use an ACF and apply the enable_allocate attribute to the relevant operation. This causes the generated server stub to set up the necessary environment. Note that memory allocated by allocators other than rpc_ss_allocate() is not released when the operation on the server side completes execution. If you want to use rpc_ss_allocate() outside the code called from a server stub, you must first create an environment for it by calling rpc_ss_enable_allocate(). See the OSF DCE Application Development Guide for more information. RETURN VALUES A pointer to the allocated memory. An exception, rpc_x_no_memory, when no memory is available for allocation. RELATED INFORMATION Functions: rpc_ss_free rpc_ss_enable_allocate rpc_ss_disable_allocate rpc_ss_get_thread_handle rpc_ss_set_thread_handle 4 rpc_ss_bind_authn_client NAME rpc_ss_bind_authn_client - Authenticates a client's identity to a server from a client stub SYNOPSIS #include void rpc_ss_bind_authn_client( rpc_binding_handle_t *binding, if_handle_t if_handle, error_status_t *status ); PARAMETERS Input/Output binding A pointer to the server binding handle for the remote procedure call to which the routine will add authentication and authorization context. Input if_handle A stub-generated data structure that specifies the interface of interest. The routine can use this parameter to resolve a partial binding or to distinguish between interfaces. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. Possible status codes and their meanings include: error_status_ok Success. rpc_s_no_more_bindings Directs the client stub not to look for another server binding. DESCRIPTION The rpc_ss_bind_authn_client() routine is a DCE-supplied binding callout routine for use with the binding_callout ACF interface attribute. The binding_callout attribute enables applications to specify the name of a routine that the client stub will call automatically to modify a server binding handle with additional information before it initiates a remote procedure call. This attribute is especially useful for applications using the automatic binding method, where it is the client stub that obtains the binding handle, rather than the application code. The binding_callout attribute provides these applications with a way to gain access to a server binding handle from the client stub, since the handle is not accessible from the application code. Applications can specify rpc_ss_bind_authn_client() to the binding_callout ACF interface attribute in order to authenticate the client's identity to a server from the client stub before the remote procedure call to the server is initiated. This routine performs one-way authentication: the client does not care which server principal receives the remote procedure call request, but the server verifies that the client is who the client claims to be. The routine sets the protection level used, the authentication identity, and the authentication service used to their default values; see the rpc_binding_set_auth_info reference pages for more information on these default values. It sets the authorization service to perform authorization based on the client's principal name. Applications can also specify user-written binding callout routines with the binding_callout attribute to modify server binding handles from client stubs with other types of information. See the OSF DCE Application Development Guide-Core Components for more information on using the binding_callout ACF attribute. RETURN VALUES None. RELATED INFORMATION Functions: rpc_binding_set_auth_info rpc_ep_resolve_binding rpc_mgmt_inq_server_princ_name Books: OSF DCE Application Development Guide-Introduction & Style Guide OSF DCE Application Development Guide-Core Components 4 rpc_ss_client_free NAME rpc_ss_client_free - Frees memory returned from a client stub Used by client applications. SYNOPSIS #include void rpc_ss_client_free( idl_void_p_t node_to_free ); PARAMETERS Input node_to_free Specifies a pointer to memory returned from a client stub. DESCRIPTION The rpc_ss_client_free() routine releases memory allocated and returned from a client stub. The thread calling rpc_ss_client_free() must have the same thread handle as the thread that made the RPC call. This routine enables a routine to deallocate dynamically allocated memory returned by an RPC call without knowledge of the memory management environment from which it was called. Note that while this routine is always called from client code, the code can be executing as part of another server. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_ss_free rpc_ss_get_thread_handle rpc_ss_set_client_alloc_free rpc_ss_set_thread_handle rpc_ss_swap_client_alloc_free 4 rpc_ss_destroy_client_context NAME rpc_ss_destroy_client_context - Reclaims the client memory resources for the context handle, and sets the context handle to NULL Used by client applications. SYNOPSIS #include void rpc_ss_destroy_client_context( void *p_unusable_context_handle ); PARAMETERS Input p_unusable_context_handle Specifies the context handle that can no longer be accessed. DESCRIPTION The rpc_ss_destroy_client_context() routine is used by the client application to reclaim the client resources used in maintaining an active context handle. Only call this after a communications error makes the context handle unusable. When rpc_ss_destroy_client_context() reclaims the memory resources, it also sets the context handle to null. RETURN VALUES No value is returned. The rpc_ss_destroy_client_context() routine raises no exceptions. 4 rpc_ss_disable_allocate NAME rpc_ss_disable_allocate - Releases resources and allocated memory Used by client applications. SYNOPSIS #include void rpc_ss_disable_allocate( void ); DESCRIPTION The rpc_ss_disable_allocate() routine releases (disables) all resources acquired by a call to rpc_ss_enable_allocate(), and any memory allocated by calls to rpc_ss_allocate() after the call to rpc_ss_enable_allocate() was made. The rpc_ss_enable_allocate() and rpc_ss_disable_allocate() routines must be used in matching pairs. For information about rules for using memory management routines, see the OSF DCE Application Development Guide. RELATED INFORMATION Functions: rpc_ss_allocate rpc_ss_enable_allocate Books: OSF DCE Application Development Guide 4 rpc_ss_enable_allocate NAME rpc_ss_enable_allocate - Enables the allocation of memory by the rpc_ss_allocate() routine when not in manager code Used by client applications. SYNOPSIS #include void rpc_ss_enable_allocate( void ); DESCRIPTION In sophisticated servers, it may be necessary to call manager code routines from different environments. This occurs, for example, when the application is both a client and a server of the same interface. Therefore, a manager code routine may need to be called both by the application code and by the stub code. If code, other than manager code, calls the rpc_ss_allocate() routine, it must first call rpc_ss_enable_allocate() to initialize the memory management environment that rpc_ss_allocate() uses. For information about rules for using memory management routines, see the OSF DCE Application Development Guide. RETURN VALUES An exception, rpc_x_no_memory, when there is insufficient memory available to set up necessary data structures. RELATED INFORMATION Functions: rpc_ss_allocate rpc_ss_disable_allocate Books: OSF DCE Application Development Guide 4 rpc_ss_free NAME rpc_ss_free - Frees memory allocated by the rpc_ss_allocate() routine Used by server or possibly by client applications. SYNOPSIS #include void rpc_ss_free( idl_void_p_t node_to_free ); PARAMETERS Input node_to_free Specifies a pointer to memory allocated by rpc_ss_allocate(). Note that in ANSI standard C environments, idl_void_p_t is defined as void * and in other environments is defined as char *. DESCRIPTION The rpc_ss_free() routine releases memory allocated by rpc_ss_allocate(). The thread calling rpc_ss_free() must have the same thread handle as the thread that allocated the memory with rpc_ss_allocate(). Use it only in an environment where rpc_ss_allocate() is used. If the manager code allocates memory with rpc_ss_allocate() and the memory is not released by rpc_ss_free() during manager code execution, then the server stub automatically releases the memory when the manager code completes execution and returns control to the stub. Manager code can also use rpc_ss_free() to release memory that is pointed to by a full pointer in an input parameter. For information about rules for using memory management routines, see the OSF DCE Application Development Guide. RELATED INFORMATION Functions: rpc_ss_allocate rpc_ss_get_thread_handle rpc_ss_set_thread_handle Books: OSF DCE Application Development Guide 4 rpc_ss_get_thread_handle NAME rpc_ss_get_thread_handle - Gets a thread handle for the manager code before it spawns additional threads, or for the client code when it becomes a server Used by server or possibly by client applications. SYNOPSIS #include rpc_ss_thread_handle_t rpc_ss_get_thread_handle( void ); DESCRIPTION The rpc_ss_get_thread_handle() routine is used by a server manager thread when it spawns additional threads. To spawn additional threads that are able to perform memory management, the server manager code calls rpc_ss_get_thread_handle() and passes the thread handle to each spawned thread. Each spawned thread that uses rpc_ss_allocate() and rpc_ss_free() for memory management must first call rpc_ss_set_thread_handle(), using the handle obtained by the original manager thread. The rpc_ss_get_thread_handle() routine can also be used when a program changes from being a client to being a server. The program gets a handle on its environment as a client by calling rpc_ss_get_thread_handle(). When the program reverts to being a client it re-establishes the client environment by calling rpc_ss_set_thread_handle(), supplying the previously obtained handle as a parameter. RETURN VALUES A thread handle. EXAMPLES This function determines the thread handle, creates a thread, and passes the thread handle to the thread so it can share the memory management environment of the calling thread. #include #include pthread_t Launch_thread( int (*routine_to_launch)(pthread_addr_t th) ) { rpc_ss_thread_handle_t th = rpc_ss_get_thread_handle(); pthread_t t; /* * Create the thread and pass to it the thread handle * so it can use rpc_ss_set_thread_handle. */ pthread_create( &t, pthread_attr_default, (pthread_startroutine_t)routine_to_launch, (pthread_addr_t)th ); return t; } RELATED INFORMATION Functions: rpc_ss_allocate rpc_ss_free rpc_ss_set_thread_handle 4 rpc_ss_set_client_alloc_free NAME rpc_ss_set_client_alloc_free - Sets the memory allocation and freeing mechanism used by the client stubs, thereby overriding the default routines the client stub uses to manage memory for pointed-to nodes Used by client applications. SYNOPSIS #include void rpc_ss_set_client_alloc_free( idl_void_p_t (*p_allocate)(idl_size_t size), void (*p_free)(idl_void_p_t *ptr) ); PARAMETERS Input p_allocate Specifies a pointer to a routine that has the same procedure declaration as the malloc() routine and that is used by the client stub to allocate memory. p_free Specifies a pointer to a routine that has the same procedure declaration as the free() routine and that is used to free memory that was allocated using the routine pointed at by p_allocate. Note that in ANSI standard C environments, idl_void_p_t is defined as void * and in other environments is defined as char *. DESCRIPTION The rpc_ss_set_client_alloc_free() routine overrides the default routines that the client stub uses to manage memory for pointed-to nodes. The default memory management routines are malloc() and free(), except when the remote call occurs within manager code, in which case the default memory management routines are rpc_ss_allocate() and rpc_ss_free(). For information about rules for using memory management routines, see the OSF DCE Application Development Guide. RETURN VALUES An exception, rpc_x_no_memory, when there is insufficient memory available to set up necessary data structures. RELATED INFORMATION Functions: rpc_ss_allocate rpc_ss_free Books: OSF DCE Application Development Guide 4 rpc_ss_set_thread_handle NAME rpc_ss_set_thread_handle - Sets the thread handle for either a newly created spawned thread or for a server that was formerly a client and is ready to be a client again Used by server or possibly by client applications. SYNOPSIS #include void rpc_ss_set_thread_handle( rpc_ss_thread_handle_t id ); PARAMETERS Input id A thread handle returned by a call to rpc_ss_get_thread_handle(). DESCRIPTION The rpc_ss_set_thread_handle() routine is used by a thread spawned in the manager code to associate itself with the main RPC manager thread. Each spawned thread that uses rpc_ss_allocate() and rpc_ss_free() for memory management must call rpc_ss_set_thread_handle(), using the handle that the main RPC manager thread obtained through rpc_ss_get_thread_handle(). The rpc_ss_set_thread_handle() routine can also be used by a program that originally was a client, then became a server, and is now reverting to a client. The program must re-establish the client environment by calling the rpc_ss_set_thread_handle() routine, supplying the handle it received (through rpc_ss_get_thread_handle()) prior to becoming a server, as a parameter. RETURN VALUES An exception, rpc_x_no_memory, when there is insufficient memory available to set up necessary data structures. EXAMPLES When this function is invoked within a spawned thread, its argument is the thread handle of the calling thread. This example assumes the data passed to the thread consists of only the middle thread. #include #include int helper_thread (pthread_addr_t th) { /* * Set the memory management environment to match * the parent environment. */ rpc_ss_set_thread_handle(rpc_ss_thread_handle_t)th; /* * Real work of this thread follows here ... */ } RELATED INFORMATION Functions: rpc_ss_get_thread_handle rpc_ss_allocate rpc_ss_free Books: OSF DCE Application Development Guide 4 rpc_ss_swap_client_alloc_free NAME rpc_ss_swap_client_alloc_free - Exchanges the current memory allocation and freeing mechanism used by the client stubs with one supplied by the client Used by client applications. SYNOPSIS #include void rpc_ss_swap_client_alloc_free( idl_void_p_t (*p_allocate)(idl_size_t size), void (*p_free)(idl_void_p_t ptr), idl_void_p_t (**p_p_old_allocate)(idl_size_t size), void (**p_p_old_free)(idl_void_p_t ptr) ); PARAMETERS Input p_allocate Specifies a pointer to a routine that has the same procedure declaration as the malloc() routine and that is used for allocating client stub memory. p_free Specifies a pointer to a routine that has the same procedure declaration as the free() routine and that is used for freeing client stub memory. Output p_p_old_allocate Specifies a pointer to a pointer to a routine that has the same procedure declaration as the malloc() routine. A pointer to the routine that was previously used to allocate client stub memory is returned in this parameter. p_p_old_free Specifies a pointer to a pointer to a routine that has the same procedure declaration as the free() routine. A pointer to the routine that was previously used to free client stub memory is returned in this parameter. Note that in ANSI standard C environments, idl_void_p_t is defined as void * and in other environments is defined as char *. DESCRIPTION The rpc_ss_swap_client_alloc_free() routine exchanges the current client allocate and free mechanism used by the client stubs for one supplied by the caller. If it is appropriate for the client code called by an application to use a certain memory allocation and freeing mechanism, regardless of its caller's state, the client code can swap its own mechanism into place on entry, replacing its caller's mechanism. It can then swap the caller's mechanism back into place prior to returning. For information about rules for using memory management routines, see the OSF DCE Application Development Guide. RETURN VALUES An exception, rpc_x_no_memory, is returned when there is insufficient memory available to set up necessary data structures. RELATED INFORMATION Functions: rpc_ss_allocate rpc_ss_free rpc_ss_set_client_alloc_free Books: OSF DCE Application Development Guide 4 rpc_string_binding_compose NAME rpc_string_binding_compose - Combines the components of a string binding into a string binding Used by client or server applications. SYNOPSIS #include void rpc_string_binding_compose( unsigned_char_t *obj_uuid, unsigned_char_t *protseq, unsigned_char_t *network_addr, unsigned_char_t *endpoint, unsigned_char_t *options, unsigned_char_t **string_binding, unsigned32 *status ); PARAMETERS Input obj_uuid Specifies a NULL-terminated string representation of an object UUID. protseq Specifies a NULL-terminated string representation of a protocol sequence. network_addr Specifies a NULL-terminated string representation of a network address. endpoint Specifies a NULL-terminated string representation of an endpoint. options Specifies a NULL-terminated string representation of network options. Output string_binding Returns a pointer to a NULL-terminated string representation of a binding handle. Specify NULL to prevent the routine from returning this argument. In this case the application does not call rpc_string_free(). status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status code and its meaning is as follows: rpc_s_ok Success. DESCRIPTION The rpc_string_binding_compose() routine combines string binding handle components into a string binding handle. The RPC runtime allocates memory for the string returned in the string_binding parameter. The application calls rpc_string_free() to deallocate that memory. Specify NULL or provide a null string (\0) for each input string that has no data. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_from_string_binding rpc_binding_to_string_binding rpc_string_binding_parse rpc_string_free uuid_to_string 4 rpc_string_binding_parse NAME rpc_string_binding_parse - Returns, as separate strings, the components of a string binding Used by client or server applications. SYNOPSIS #include void rpc_string_binding_parse( unsigned_char_t *string_binding, unsigned_char_t **obj_uuid, unsigned_char_t **protseq, unsigned_char_t **network_addr, unsigned_char_t **endpoint, unsigned_char_t **network_options, unsigned32 *status ); PARAMETERS Input string_binding Specifies a NULL-terminated string representation of a binding. Output obj_uuid Returns a pointer to a NULL-terminated string representation of an object UUID. Specify NULL to prevent the routine from returning this parameter. In this case the application does not call rpc_string_free(). protseq Returns a pointer to a NULL-terminated string representation of a protocol sequence. Specify NULL to prevent the routine from returning this parameter. In this case the application does not call rpc_string_free(). network_addr Returns a pointer to a NULL-terminated string representation of a network address. Specify NULL to prevent the routine from returning this parameter. In this case the application does not call rpc_string_free(). endpoint Returns a pointer to a NULL-terminated string representation of an endpoint. Specify NULL to prevent the routine from returning this parameter. In this case the application does not call rpc_string_free(). network_options Returns a pointer to a NULL-terminated string representation of network options. Specify NULL to prevent the routine from returning this parameter. In this case the application does not call rpc_string_free(). status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_invalid_string_binding Invalid string binding. DESCRIPTION The rpc_string_binding_parse() routine parses a string representation of a binding handle into its component fields. The RPC runtime allocates memory for each component string the routine returns. The application calls rpc_string_free() once for each returned string to deallocate the memory for that string. If any field of the string_binding field is empty, rpc_string_binding_parse() returns the empty string in the corresponding output parameter. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_binding_from_string_binding rpc_binding_to_string_binding rpc_string_binding_compose rpc_string_free uuid_from_string 4 rpc_string_free NAME rpc_string_free - Frees a character string allocated by the runtime Used by client, server, or management applications. SYNOPSIS #include void rpc_string_free( unsigned_char_t **string, unsigned32 *status ); PARAMETERS Input/Output string Specifies the address of the pointer to the character string to free. The value NULL is returned. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status code and its meaning is as follows: rpc_s_ok Success. DESCRIPTION The rpc_string_free() routine deallocates the memory occupied by a character string returned by the RPC runtime. An application must call this routine once for each character string allocated and returned by calls to other RPC runtime routines. The names of these routines appear at the end of this reference page. RETURN VALUES No value is returned. RELATED INFORMATION Functions: dce_error_inq_text rpc_binding_inq_auth_client rpc_binding_inq_auth_info rpc_binding_to_string_binding rpc_mgmt_ep_elt_inq_next rpc_mgmt_inq_server_princ_name rpc_ns_binding_inq_entry_name rpc_ns_entry_expand_name rpc_ns_group_mbr_inq_next rpc_ns_profile_elt_inq_next rpc_string_binding_compose rpc_string_binding_parse uuid_to_string 4 uuid_compare NAME uuid_compare - Compares two UUIDs and determines their order Used by client, server, or management applications. SYNOPSIS #include signed32 uuid_compare( uuid_t *uuid1, uuid_t *uuid2, unsigned32 *status ); PARAMETERS Input uuid1 Specifies a pointer to a UUID. This UUID is compared with the UUID specified in uuid2. Use the value NULL to specify a nil UUID for this parameter. uuid2 Specifies a pointer to a UUID. This UUID is compared with the UUID specified in uuid1. Use the value NULL to specify a nil UUID for this parameter. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: uuid_s_ok Success. uuid_s_bad_version Bad UUID version. DESCRIPTION The uuid_compare() routine compares two UUIDs and determines their order. A nil UUID is considered the first element in order. The order of UUIDs is defined by the RPC architecture and is not a temporal (related to time) ordering. Comparing two specific UUIDs always returns the same result regardless of the implementation or system architecture. You can use this routine to sort data with UUIDs as a key. RETURN VALUES Returns one of the following constants: -1 The uuid1 parameter precedes the uuid2 parameter in order. 0 The uuid1 parameter is equal to the uuid2 parameter in order. 1 The uuid1 parameter follows the uuid2 parameter in order. Note that a value of 0 (zero) has the same meaning as if uuid_equal(&uuid1, &uuid2) returned a value of TRUE. A nil UUID is the first UUID in order. This means the following: + If uuid1 is NULL and uuid2 is non-nil, the routine returns -1. + If uuid1 is NULL and uuid2 is NULL, the routine returns 0. + If uuid1 is non-nil and uuid2 is NULL, the routine returns 1. RELATED INFORMATION Functions: uuid_equal uuid_is_nil 4 uuid_create NAME uuid_create - Creates a new UUID Used by client, server, or management applications. SYNOPSIS #include void uuid_create( uuid_t *uuid, unsigned32 *status ); PARAMETERS Input None. Output uuid Returns the new UUID. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: uuid_s_ok Success. uuid_s_getconf_failure Cannot get network interface device configuration. uuid_s_no_address Cannot get Ethernet hardware address. uuid_s_socket_failure Cannot create socket. DESCRIPTION The uuid_create() routine creates a new UUID. RETURN VALUES No value is returned. RELATED INFORMATION Functions: uuid_create_nil uuid_from_string uuid_to_string 4 uuid_create_nil NAME uuid_create_nil - Creates a nil UUID Used by client, server, or management applications. SYNOPSIS #include void uuid_create_nil( uuid_t *nil_uuid, unsigned32 *status ); PARAMETERS Input None. Output nil_uuid Returns a nil UUID. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status code and its meaning is as follows: uuid_s_ok Success. DESCRIPTION The uuid_create_nil() routine creates a nil UUID. RETURN VALUES No value is returned. RELATED INFORMATION Functions: uuid_create 4 uuid_equal NAME uuid_equal - Determines if two UUIDs are equal Used by client, server, or management applications. SYNOPSIS #include boolean32 uuid_equal( uuid_t *uuid1, uuid_t *uuid2, unsigned32 *status ); PARAMETERS Input uuid1 Specifies a pointer to a UUID. This UUID is compared with the UUID specified in uuid2. Supply the value NULL to specify a nil UUID for this parameter. uuid2 Specifies a pointer to a UUID. This UUID is compared with the UUID specified in uuid1. Supply the value NULL to specify a nil UUID for this parameter. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: uuid_s_ok Success. uuid_s_bad_version Bad UUID version. DESCRIPTION The uuid_equal() routine compares two UUIDs and determines if they are equal. RETURN VALUES The possible return values and their meanings are as follows: TRUE The uuid1 parameter is equal to the uuid2 parameter. Parameter status contains the status code uuid_s_ok. FALSE The uuid1 parameter is not equal to the uuid2 parameter. RELATED INFORMATION Functions: uuid_compare 4 uuid_from_string NAME uuid_from_string - Converts a string UUID to its binary representation Used by client, server, or management applications. SYNOPSIS #include void uuid_from_string( unsigned_char_t *string_uuid, uuid_t *uuid, unsigned32 *status ); PARAMETERS Input string_uuid Specifies a string representation of a UUID. Supply the value NULL or the null string (\0) to specify a nil UUID. Output uuid Returns the binary form of the UUID specified by the string_uuid parameter into the address specified by this parameter. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: uuid_s_ok Success. uuid_s_bad_version Bad UUID version. uuid_s_invalid_string_uuid Invalid format for a string UUID. DESCRIPTION An application calls the uuid_from_string() routine to convert a string UUID to its binary representation. RETURN VALUES No value is returned. RELATED INFORMATION Functions: uuid_to_string 4 uuid_hash NAME uuid_hash - Creates a hash value for a UUID Used by client, server, or management applications. SYNOPSIS #include unsigned16 uuid_hash( uuid_t *uuid, unsigned32 *status ); PARAMETERS Input uuid Specifies the UUID for which a hash value is created. Supply NULL to specify a nil UUID for this parameter. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: uuid_s_ok Success. uuid_s_bad_version Bad UUID version. DESCRIPTION The uuid_hash() routine generates a hash value for a specified UUID. Note that the return value for a single uuid value may differ across platforms. RETURN VALUES Returns a hash value for the specified UUID. 4 uuid_is_nil NAME uuid_is_nil - Determines if a UUID is nil Used by client, server, or management applications. SYNOPSIS #include boolean32 uuid_is_nil( uuid_t *uuid, unsigned32 *status ); PARAMETERS Input uuid Specifies a UUID to test as a nil UUID. Supply NULL to specify a nil UUID for this parameter. Output status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: uuid_s_ok Success. uuid_s_bad_version Bad UUID version. DESCRIPTION The uuid_is_nil() routine determines whether the specified UUID is a nil UUID. This routine yields the same result as if an application did the following: + Called the uuid_create_nil() routine. + Called the uuid_equal() routine to compare the returned nil UUID to the UUID specified in the uuid parameter. RETURN VALUES The possible return values and their meanings are as follows: TRUE The uuid parameter is a nil UUID. Parameter status contains the status code uuid_s_ok. FALSE The uuid parameter is not a nil UUID. RELATED INFORMATION Functions: uuid_compare uuid_create_nil uuid_equal 4 uuid_to_string NAME uuid_to_string - Converts a UUID from a binary representation to a string representation Used by client, server, or management applications. SYNOPSIS #include void uuid_to_string( uuid_t *uuid, unsigned_char_t **string_uuid, unsigned32 *status ); PARAMETERS Input uuid Specifies a UUID in its binary format. Supply NULL to specify a nil UUID for this parameter. Output string_uuid Returns a pointer to the string representation of the UUID specified in the uuid parameter. Specify NULL for this parameter to prevent the routine from returning this information. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: uuid_s_ok Success. uuid_s_bad_version Bad UUID version. DESCRIPTION The uuid_to_string() routine converts a UUID from its binary representation to its string representation. The RPC runtime allocates memory for the string returned in the string_uuid parameter. The application calls rpc_string_free() to deallocate that memory. It is not necessary to call rpc_string_free() when you supply NULL for the string_uuid parameter. RETURN VALUES No value is returned. RELATED INFORMATION Functions: rpc_string_free uuid_from_string 4 wchar_t_from_netcs NAME wchar_t_from_netcs - Converts international character data from a network code set to a local code set Used by client and server applications. SYNOPSIS #include void wchar_t_from_netcs( rpc_binding_handle_t binding, unsigned32 network_code_set_value, idl_byte *network_data, unsigned32 network_data_length, unsigned32 local_buffer_size, wchar_t *local_data, unsigned32 *local_data_length, error_status_t *status ); PARAMETERS Input binding Specifies the target binding handle from which to obtain code set conversion information. When called from the client stub, this value is the binding handle of a compatible server returned by the rpc_ns_binding_import_next() or rpc_ns_binding_select() routine. When called from the server stub, this value is a pointer to binding information that the client stub passed in the RPC call. network_code_set_value The registered hexadecimal integer value that represents the code set that was used to transmit character data over the network. In general, the "network" code set is the code set that the client application's code sets evaluation routine has determined to be compatible for this client and server. When the caller is the client stub, this value is the receiving tag. When the caller is the server stub, this value is the sending tag. network_data A pointer to the international character data that has been received, in the network code set encoding. network_data_length The number of byte data elements to be converted. This is the size of the byte string that was sent through the network. local_buffer_size A pointer to the buffer size to be allocated to contain the converted data, in units of wchar_t. The value specified in this parameter is the local buffer size returned by the wchar_t_local_size() routine. Output local_data A pointer to the converted data, in wchar_t format. local_data_length The length of the converted data, in units of wchar_t. Specify NULL if a fixed array is to be converted. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_ss_incompatible_codesets The specified code set does not match the code set specified in the sending tag in the binding handle. If this error occurs in the server stub, an exception is raised to the client application. When the routine is running the host converter routines, the following errors can be returned: rpc_s_ss_invalid_char_support rpc_s_ss_short_conv_buffer rpc_s_ss_iconv_error (HP-UX reference platform only) rpc_s_ss_no_memory (HP-UX reference platform only) When invoked from the server stub, this routine calls the dce_cs_loc_to_rgy() routine and the host converter routines. If one of these routines returns an error, an exception is raised to the client application. DESCRIPTION The wchar_t_from_netcs() routine belongs to a set of DCE RPC routines for use by client and server applications that are transferring international character data in a heterogeneous character set and code sets environment. The wchar_t_from_netcs() routine is one of the DCE RPC stub code set conversion routines that RPC stubs use before they marshall or unmarshall data to convert international character data to and from local and network code sets. Client and server stubs call the wchar_t_*_netcs routines when the wchar_t type has been specified as the local data type using the cs_char attribute in the attribute configuration file for the application. Client and server stubs call the wchar_t_from_netcs() routine before they unmarshall the international character data received from the network. The routine takes a binding handle, a code set value that identifies the code set used to transfer international character data over the network, the address of the network data, in idl_byte format, that may need to be converted, and the data length, in units of idl_byte. The routine compares the sending code set to the local code set currently in use. If the routine finds that code set conversion is necessary, (because the local code set differs from the code set specified to be used on the network), it determines which host code set converter to call to convert the data and then invokes that converter. The routine then returns the converted data, in wchar_t format. If the data is a varying, conformant, or conformant varying array, the routine also returns the length of the converted data, in units of wchar_t. Applications can specify local data types other than cs_byte and wchar_t (the local data types for which DCE RPC supplies stub code set conversion routines) with the cs_char ACF attribute. In this case, the application must also supply local_type_to_netcs() and local_type_from_netcs() stub conversion routines for this type. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: cs_byte_from_netcs cs_byte_to_netcs wchar_t_to_netcs 4 wchar_t_local_size NAME wchar_t_local_size - Calculates the necessary buffer size for code set conversion from a network code set to a local code set Used by client and server applications. SYNOPSIS #include void wchar_t_local_size( rpc_binding_handle_t binding, unsigned32 network_code_set_value, unsigned32 network_buffer_size, idl_cs_convert_t *conversion_type, unsigned32 *local_buffer_size, error_status_t *status ); PARAMETERS Input binding Specifies the target binding handle from which to obtain buffer size evaluation information. When called from the client stub, this value is the binding handle of a compatible server returned by the rpc_ns_binding_import_next() or rpc_ns_binding_select() routine. When called from the server stub, this value is a pointer to binding information that the client stub passed in the RPC call. network_code_set_value The registered hexadecimal integer value that represents the code set used to transmit character data over the network. In general, the "network" code set is the code set that the client application's code sets evaluation routine has determined to be compatible for this client and server. When the caller is the client stub, this value is the receiving tag. When the caller is the server stub, this value is the sending tag. network_buffer_size The size, in units of idl_byte, of the buffer that is allocated for the international character data, For a conformant or conformant varying array, this value is the network value of the size_is variable for the array; that is, the value is the size of the unmarshalled string if no conversion is done. Output conversion_type A pointer to the enumerated type defined in dce/idlbase.h that indicates whether data conversion is necessary and whether or not the existing buffer is sufficient for storing the results of the conversion. Since idl_byte to wchar_t conversion always takes place, and idl_byte and wchar_t require a different number of bytes, the conversion type is always idl_cs_new_buffer_convert, which means that the converted data must be written to a new buffer. local_buffer_size A pointer to the buffer size that needs to be allocated to contain the converted data, in units of wchar_t. This value is to be used as the local value of the size_is variable for the array, and is non-NULL only if a conformant or conformant varying array is to be unmarshalled. A value of NULL in this parameter indicates that a fixed or varying array is to be unmarshalled. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_ss_incompatible_codesets The specified code set does not match the code set specified in the sending tag in the binding handle. If this error occurs in the server stub, an exception is raised to the client application. When invoked from the server stub, this routine calls the routines dce_cs_loc_to_rgy() and rpc_rgy_get_max_bytes(). If either of these routines returns an error, the wchar_t_local_size() routine raises an exception to the client application. DESCRIPTION The wchar_t_local_size() routine belongs to a set of DCE RPC routines for use by client and server applications that are transferring international character data in a heterogeneous character set and code sets environment. The wchar_t_local_size() routine is one of the DCE RPC buffer sizing routines that RPC stubs use before they marshall or unmarshall data to determine whether or not the buffers allocated for code set conversion need to be enlarged to hold the converted data. The buffer sizing routines determine the type of conversion required and calculate the size of the necessary buffer (if a conformant or conformant varying array is to be marshalled). The RPC stub then allocates a buffer of that size before it calls one of the code set conversion routines. Client and server stubs call the wchar_t_*_size routines when the wchar_t type has been specified as the argument to the cs_char attribute in the attribute configuration file for the application. Applications do not call wchar_t_local_size() routine directly. Client and server stubs call the routine before they unmarshall any data. The stubs pass the routine a binding handle and a code set value that identifies the code set that was used to transfer international character data over the network. The stubs also specify the network storage size of the data, in units of idl_byte. When called from a client stub, the wchar_t_local_size() routine determines the value of conversion_type from conversion method and tag information set up in the binding handle by a code sets evaluation routine or a tag-setting routine. Since idl_byte to wchar_t require different numbers of bytes to encode one character unit, the routine always sets the value to idl_cs_new_buffer_convert, which means that the converted data must be written to a new buffer. The routine sets the conversion_type parameter to this value and, if a conformant or conformant varying array is to be unmarshalled, calculates a new buffer size by dividing the value of network_buffer_size by the number of bytes required to encode one wchar_t unit. The routine returns the new buffer size in the local_buffer_size parameter. The size is specified in units of wchar_t, which is the local representation used for international character data. In cases where the binding handle does not contain the results of character and code sets evaluation, or where it is being called from the server stub, the wchar_t_local_size() routine determines the value of conversion_type itself using the local code set value and the code set value passed in the network_code_set_value parameter and returns the appropriate conversion_type value. If a conformant or conformant varying array is to be unmarshalled, the routine calculates the size of this new buffer (by multiplying the value of network_buffer_size by dividing the value of network_buffer_size by the number of bytes required to encode one wchar_t unit, and returns the results, in units of wchar_t, in local_buffer_size. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: byte_net_size byte_local_size wchar_t_net_size 4 wchar_t_net_size NAME wchar_t_net_size - Calculates the necessary buffer size for code set conversion from a local code set to a network code set Used by client and server applications. SYNOPSIS #include void wchar_t_net_size( rpc_binding_handle_t binding, unsigned32 network_code_set_value, unsigned32 local_buffer_size, idl_cs_convert_t *conversion_type, unsigned32 *network_buffer_size, error_status_t *status ); PARAMETERS Input binding Specifies the target binding handle from which to obtain buffer size evaluation information. When called from the client stub, this value is the binding handle of a compatible server returned by the rpc_ns_binding_import_next() or rpc_ns_binding_select() routine. When called from the server stub, this value is a pointer to binding infor mation that the client stub passed in the RPC call. network_code_set_value The registered hexadecimal integer value that represents the code set to be used to transmit character data over the network. In general, the "network" code set is the code set that the client application's code sets evaluation routine has determined to be compatible for this client and server. When the caller is the client stub, this value is the sending tag. When the caller is the server stub, this value is the receiving tag. local_buffer_size The size, in units of wchar_t, of the buffer that is allocated for the international character data. This value is the local value of the size_is variable for the array; that is, the value is the size of the marshalled string if no conversion is done. Output conversion_type A pointer to the enumerated type defined in dce/idlbase.h that indicates whether data conversion is necessary and whether or not the existing buffer is sufficient for storing the results of the conversion. Because wchar_t to cs_byte conversion always takes place, and because wchar_t and cs_byte are different units, the conversion type returned is always idl_cs_new_buffer_convert, which means that the converted data must be written to a new buffer. network_buffer_size A pointer to the buffer size that needs to be allocated to contain the converted data, in units of idl_byte. This value is to be used as the network value of the size_is variable for the array, and is non-NULL only if a conformant or conformant varying array is to be marshalled. A value of NULL in this parameter indicates that a fixed or varying array is to be marshalled. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_ss_incompatible_codesets The specified code set does not match the code set specified in the sending tag in the binding handle. If this error occurs in the server stub, an exception is raised to the client application. When invoked from the server stub, this routine calls the routines dcs_cs_loc_to_rgy() and rpc_rgy_get_max_bytes(). If either of these routines returns an error, the wchar_t_net_size() routine raises an exception to the client application. DESCRIPTION The wchar_t_net_size() routine belongs to a set of DCE RPC routines for use by client and server applications that are transferring international character data in a heterogeneous character set and code sets environment. The wchar_t_net_size() routine is one of the DCE RPC buffer sizing routines that RPC stubs use before they marshall or unmarshall data to determine whether or not the buffers allocated for code set conversion need to be enlarged to hold the converted data. The buffer sizing routines determine the type of conversion required and calculate the size of the necessary buffer (if a conformant or conformant varying array is to be marshalled). The RPC stub then allocates a buffer of that size before it calls one of the code set conversion routines. Client and server stubs call the wchar_t_*_size routines when the wchar_t type has been specified as the local data type with the cs_char attribute in the attribute configuration file for the application. Applications do not call the wchar_t_net_size() routine directly. Client and server stubs call the routine before they marshall any data. The stubs pass the routine a binding handle and a code set value that identifies the code set to be used to transfer international character data over the network. The stubs also specify the local storage size of the data, in units of wchar_t. When called from a client stub, the wchar_t_net_size routine determines the value of conversion_type from conversion method and tag information set up in the binding handle by a code sets evaluation routine or a tag-setting routine. Since wchar_t and idl_byte are completely different data types, the routine always sets the value to idl_cs_new_buffer_convert. The routine sets the conversion_type parameter to this value and, if a conformant or conformant varying array is to be marshalled, calculates a new buffer size by multiplying the value of local_buffer_size by the byte size for wchar_t. The routine returns the new buffer size in the network_buffer_size parameter. The size is specified in units of idl_byte, which is the network representation used for international character data. In cases where the binding handle does not contain the results of character and code sets evaluation, or where it is being called from the server stub, the wchar_t_net_size routine determines the value of conversion_type itself using the local code set value and the code set value passed in the network_code_set_value parameter, and returns the appropriate conversion_type value. If a conformant or conformant varying array is to be marshalled, and the routine finds that a new buffer is required to hold the converted data, the routine calculates the size of this new buffer (by multiplying the value of local_buffer_size by sizeof(wchar_t); that is, the number of bytes required to encode one wchar_t data type, returns the results, in units of idl_byte, in network_buffer_size. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: byte_local_size byte_net_size wchar_t_local_size 4 wchar_t_to_netcs NAME wchar_t_to_netcs - Converts international character data from a local code set to a network code set Used by client and server applications. SYNOPSIS #include void wchar_t_to_netcs( rpc_binding_handle_t binding, unsigned32 network_code_set_value, wchar_t *local_data, unsigned32 local_data_length, idl_byte *network_data, unsigned32 *network_data_length, error_status_t *status ); PARAMETERS Input binding Specifies the target binding handle from which to obtain code set conversion information. When called from the client stub, this value is the binding handle of a compatible server returned by the rpc_ns_binding_import_next() or rpc_ns_binding_select() routine. When called from the server stub, this value is a pointer to binding information that the client stub passed in the RPC call. network_code_set_value The registered hexadecimal integer value that represents the code set to be used to transmit character data over the network. In general, the "network" code set is the code set that the client application's code sets evaluation routine has determined to be compatible for this client and server. When the caller is the client stub, this value is the sending tag. When the caller is the server stub, this value is the receiving tag. local_data A pointer to the international character data to be transmitted, in the local code set encoding. local_data_length The number of wchar_t data elements to be converted. For a varying array or a conformant varying array, this value is the local value of the length_is variable. For a conformant array, this value is the local value of the size_is variable. For a fixed array, the value is the array size specified in the interface definition. Output network_data A pointer to the converted data, in idl_byte format. network_data_length A pointer to the length of the converted data, in units of idl_byte. Specify NULL if a fixed or conformant array is to be converted. status Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not. The possible status codes and their meanings are as follows: rpc_s_ok Success. rpc_s_ss_incompatible_codesets The specified code set does not match the code set specified in the sending tag in the binding handle. If this error occurs in the server stub, an exception is raised to the client application. When this routine is running the host converter routines, the following errors can be returned: rpc_s_ss_invalid_char_input rpc_s_ss_short_conv_buffer rpc_s_ss_iconv_error (HP-UX reference platform only) rpc_s_ss_no_memory (HP-UX reference platform only) When invoked from the server stub, this routine calls the dce_cs_loc_to_rgy() routine and host converter routines. If any of these routines returns an error, an exception is raised to the client application. DESCRIPTION The wchar_t_to_netcs() routine belongs to a set of DCE RPC routines for use by client and server applications that are transferring international character data in a heterogeneous character set and code sets environment. The wchar_t_to_netcs() routine is one of the DCE RPC stub code set conversion routines that RPC stubs use before they marshall or unmarshall data to convert international character data to and from local and network code sets. Client and server stubs call the wchar_t_*_netcs() routines when the wchar_t type has been specified as the local data type with the cs_char attribute in the attribute configuration file for the application. Client and server stubs call the wchar_t_to_netcs() routine before they marshall any data. The routine takes a binding handle, a code set value that identifies the code set to be used to transfer international character data over the network, the address of the data that may need to be converted, and the length of the data, in units of wchar_t. The routine first converts the character data from wchar_t values to idl_byte values. The routine next compares the sending code set to the local code set currently in use. If the routine finds that code set conversion is necessary, (because the local code set differs from the code set specified to be used on the network), it determines which host code set converter to call to convert the data and then invokes that converter. The routine then returns the converted data, in units of idl_byte. If the data is a varying, conformant, or conformant varying array, the routine also returns the length of the converted data, in units of idl_byte. Applications can specify local data types other than cs_byte and wchar_t (the local data types for which DCE RPC supplies stub support routines for code set conversion) with the cs_char ACF attribute. In this case, the application must also supply local_type_to_netcs() and local_type_from_netcs() stub conversion routines for the application- defined local type. Permissions Required No permissions are required. RETURN VALUES No value is returned. RELATED INFORMATION Functions: cs_byte_from_netcs wchar_t_from_netcs cs_byte_to_netcs 3 Admin_Intro NAME rpc_intro - Introduction to DCE RPC daemon and RPC control program commands DESCRIPTION DCE RPC provides two administrative facilities, the RPC daemon and the RPC control program. These facilities are superceded by the DCE Host daemon (dced) and the DCE control program (dcecp) as of OSF DCE version 1.1. + The RPC daemon is a process that provides the Endpoint Map Service, which maintains the local endpoint map for local RPC servers and looks up endpoints for RPC clients. An endpoint is the address of a specific instance of a server executing in a particular address space on a given system (a server instance). Each endpoint can be used on a system by only one server at a time. An endpoint map is a database where servers register their binding information, including endpoints, for each of their RPC interfaces and the associated RPC objects. Each combination of binding information, interface identifier, and object UUID uses a distinct element in the local endoint map. The RPC daemon is started via the DCE setup program (@SYS$MANAGER:DCE$SETUP.COM). + The control program provides a set of commands for accessing the operations of the RPC name service interface (NSI). For managing endpoint maps, the control program supports showing endpoint map elements and removing any set of map elements from the local endpoint map or from any remote endpoint map. The rpccp command starts the RPC control program (RPCCP). EXIT VALUES The RPC control program reports DCE error messages on the command line. If the command executes successfully, the internal value returned is 1 (OpenVMS success); otherwise, the value is even (OpenVMS failure). This is different from other DCE implementations, but allows the use of standard OpenVMS mechanisms to determine success or failure upon return from a DCE utility program. RELATED INFORMATION Commands: dced, dcecp, rpccp Books: OSF DCE Administration Guide OSF DCE Application Development Guide-Core Components OSF DCE Application Development Reference 3 idl NAME idl - Invokes the Interface Definition Language (IDL) compiler SYNOPSIS idl filename [argument] ... DESCRIPTION The idl command invokes the IDL compiler to convert an interface definition, written in IDL, into output files. The output files include a header file, server stub file, client stub file, and auxiliary files. The compiler constructs the names of the output files by keeping the basename of the interface definition source file but replacing the filename extension with the new extension (or suffix and extension) appropriate to the newly generated type of output file. For example, math.idl could produce math_sstub.c or math_sstub.o for the server stub. The idl command accepts the following input: + An interface definition filename. + Arguments to indicate either special actions to be performed by the compiler, or special properties of the input or output files. The IDL compiler searches through directories for any related ACF. For example, if you compile a file named source.idl, the compiler automatically searches for a file named source.acf. The compiler also searches for any imported IDL file (and its related ACF). The compiler searches for these files using the following order: 1. The current working directory. The compiler always searches this directory unless you specify the -no_def_idir and -Idirectory arguments together. 2. Any imported directory. The compiler searches each directory you are specifying in the -Idirectory argument. 3. The system IDL directory. The compiler automatically imports nbase.idl, which resides in the system IDL directory. The compiler always searches this directory unless you specify the -no_def_idir argument. 4. The directory specified in the source filename. If you explicitly specify a directory in the source IDL pathname, then that directory is searched for the corresponding ACF. For example, $ idl /path/pathname/my_source.idl causes the IDL compiler to look for /path/pathname/my_source.acf if my_source.acf is not found in the directories in 1,2 and 3. Note that this directory is not searched for any imported IDL file or its corresponding ACF. Restrictions The following filenames are reserved by the IDL compiler. Naming an IDL file with one of these names may result in unexpected behavior. iovector.idl lbase.idl nbase.idl ncastat.idl ndrold.idl rpc.idl rpcbase.idl rpcpvt.idl rpcsts.idl rpctypes.idl twr.idl uuid.idl CAUTIONS The IDL compiler generates ANSI C code. It also supports C compilers that are not fully ANSI compliant although a warning message may occur during compilation of the stubs by the C compiler. A C compiler that is not fully ANSI compliant may generate the following warning messages: + warning: & before array or function: ignored + warning: enumeration type clash, operator = FILES SYS$SYSTEM:DCE$IDL.EXE Compiler SYS$COMMON:[DCE$LIBRARY] System IDL directory for imported files SYS$COMMON:[DCE$LIBRARY]NBASE.IDL Predefined IDL types SYS$COMMON:[DCE$LIBRARY] All .idl or .h files that are part of DCE RPC RELATED INFORMATION Books: OSF DCE Application Development Guide 4 ARGUMENTS 5 -client -client file_type Determines which client files to generate. If you do not specify this argument, the compiler generates all client files. The file types are as follows: none Does not generate client files. stub Generates only a client stub file. aux Generates only a client auxiliary file. A client auxiliary file is generated only if the interface contains any out-of- line or self-pointing types. all Generates client stub and client auxiliary files. This is the default and is the same as not specifying the -client argument. 5 -server -server file_type Determines which server files to generate. If you do not specify this argument, the compiler generates all server files. The file types are as follows: none Does not generate server files. stub Generates only a server stub file. aux Generates only a server auxiliary file. A server auxiliary file is generated only if the interface contains any out-of-line, self-pointing, or pipe types. all Generates server stub and server auxiliary files. This is the default and is the same as not specifying the -server argument. 5 -standard -standard standard_type - Allows you to specify portable or extended features of the OSF DCE. This option is useful when you perform builds. The standard_type argument specifies what IDL features to enable. If you do not specify this argument, the compiler generates warning messages for all features that are not available in the previous version of OSF DCE. You can specify one of the following values for the standard_type argument: portable Allows only the language features available in OSF DCE Version 1.0.2. dce_v10 Synonymous with the portable argument. dec_v10 Allows all language features supported by the standard dce_v10 argument, plus a set of HP extensions to its products based on OSF DCE Version 1.0. extended Allows all language features supported in the current version of the compiler. This is the default. dce_v11 Synonymous with the extended argument. The following example command line compiles the IDL interface test.idl and enables extended features of the OSF DCE: % idl test.idl -standard extended 5 -cstub -cstub filename Specifies a pathname for the client stub file. When you give a filename, do not give a file extension; the idl compiler appends .c to the C source file and .o to the object file. If you do not use the -cstub argument, the idl compiler appends _cstub.c to the C source file and _cstub.o to the object file. If the -lang cxx option is used, the source file will have the .cxx extension. 5 -sstub -sstub filename Specifies a pathname for the server stub file. When you give a filename, do not give a file extension; the idl compiler appends .c to the C source file and .o to the object file. If you do not use the -sstub argument, the idl compiler appends _sstub.c to the C source file and _sstub.o to the object file. If the -lang cxx option is used, the source file will have the .cxx extension. 5 -caux -caux filename Specifies a pathname for the client auxiliary file. When you give a filename, do not give a file extension; the idl compiler appends .c to the C source file and .o to the object file. If you do not use the -caux argument, the idl compiler appends _caux.c to the C source file and _caux.o to the object file. If the -lang cxx option is used, the source file will have the .cxx extension. 5 -saux -saux filename Specifies a pathname for the server auxiliary file. When you give a filename, do not give a file extension; the idl compiler appends .c to the C source file and .o to the object file. If you do not use the -caux argument, the idl compiler appends _saux.c to the C source file and _saux.o to the object file. If the -lang cxx option is used, the source file will have the .cxx extension. 5 -header -header header_file Allows you to specify a name for the generated header file. By default the compiler takes the basename of the IDL file and appends the .h extension to it. 5 -out -out directory Places the output files in the directory you specify. By default the compiler places the output files in the current working directory. 5 -Idirectory -Idirectory Specifies a directory name that contains imported interface definition files. You can specify more than one directory by specifying additional -Idirectory arguments on the command line. The compiler searches the directories in the order you list them. If a file is present in more than one directory, the compiler takes the first occurrence of the file. The default behavior of the compiler is to first search the current directory, then all directories you specify, then the system IDL directory. The directory you specify is also passed to the C preprocessor and the C compiler. 5 -no_def_idir -no_def_idir Specifies that the compiler search only the current directory for imported files. When you use this with -Idirectory, the compiler searches only the directories you list, not the current directory, and not the system IDL directory. 5 -no_mepv -no_mepv Causes the compiler to not generate a manager entry point vector (EPV) in the server stub. Use this argument if the manager code and IDL file do not use the same operation names. If you specify this argument you must provide an EPV within the manager code that can be used when the interface is registered with the RPC server runtime. The name of the type that you construct an EPV with is if_name_vmajor-version_minor-version_epv_t where if_name is the interface name. It is not necessary to use this argument if the operation names in the manager code and IDL file are the same. In this case, the compiler generates a manager EPV in the server stub using the names of the operations in the IDL file. (For information on registering the server, see the intro and rpc_server_register_if reference pages. See the OSF DCE Application Development Guide.) 5 -cepv -cepv Generates local routines in the client stub file(_cstub.c) and defines a Client Entry Point Vector (CEPV) of the name if_name_vmajor-version_minor-version_c_epv where if_name is the interface name. The CEPV contains the addresses of the local routines. The client code must call the routines indirectly by using the addresses in the CEPV; otherwise, the stub routines in the client stub file must have the same names as the operations in the IDL file. (For information on registering the server, see the intro and rpc_server_register_if reference pages. See the OSF DCE Application Development Guide.) 5 -cpp_cmd -cpp_cmd 'c_preprocessor_command_line' Allows you to specify a C preprocessor other than the default. The compiler invokes the C preprocessor found in that command line. The output of the C preprocessor is an expanded version of the input file(s) containing replacement text for any preprocessor directives (for example, the #include preprocessor directive). 5 -cpp_opt -cpp_opt 'command_options' Specifies additional options to be passed to the C preprocessor. You can add options to the command line used to invoke the C preprocessor independent of the -cpp_cmd argument. The IDL compiler concatenates the -cpp_cmd, -cpp_opt, -D, -U, -I arguments and the source filename into a command used to invoke the C preprocessor. The compiler repeats this process for each Attribute Configuration File (ACF) and IDL file. 5 -no_cpp -no_cpp Does not invoke the C preprocessor. Note that the C preprocessor must be run on files that contain preprocessor directives (such as #include) in the interface definition. 5 -cc_cmd -cc_cmd 'command_line' Invokes the C compiler and compiler options you specify in the 'command_line' argument rather than the default C compiler and compiler options. When used with the -lang cxx option, the -cc_cmd option specifies the C++ compiler. 5 -cc_opt -cc_opt 'command_options' Specifies additional options to be passed to the C compiler. You can add options to the command line used to invoke the C compiler independent of the -cc_cmd argument. The IDL compiler concatenates the -cc_cmd, -cc_opt, -I arguments and the source filename into a command that invokes the C compiler. This procedure is done for each generated stub or auxiliary file. When used with the -lang cxx option, the -cc_opt option specifies the C++ compiler options. 5 -Dname -Dname[=definition] Defines a symbol name and an optional value to be passed to the C preprocessor. You can use this method of defining a symbol instead of using #define in the source code. You can use more than one -Dname argument on the command line. This argument has no effect if you use the -no_cpp argument. 5 -Uname -Uname Removes (undefines) any initial definition of a symbol name as defined by -Dname. You can use this method to remove a symbol name instead of using #undef in the source code. You can use more than one -Uname argument on the command line. This argument has no effect if you use the -no_cpp argument. If you define and undefine a name on the same command line, undefining takes precedence. 5 -space_opt -space_opt Generates code for the marshalling and unmarshalling of data that is optimized for space, rather than speed. 5 -syntax_only -syntax_only Checks only the syntax of the IDL file, but does not generate any output files. 5 -keep -keep file_types Specifies which files to retain. To produce the object modules, the IDL compiler first creates C source modules, then invokes the target C compiler to produce object modules, and finally, deletes the C source modules. If you do not use -keep, only the object modules are saved. The file types are as follows: none Does not save the C source or the object modules. Does not invoke the C compiler. c_source Saves only the C source modules. Does not invoke the C compiler. object Saves only the object modules. all Saves both the C source and the object modules. 5 -bug -bug n, -no_bug n Retains (-bug) or does not retain (-no_bug) a specified bug from earlier IDL compiler versions. (This in an NCS compatibility argument and is not supported in OSF DCE Version 1.1). 5 -stdin -stdin Takes the standard output of a previous utility as the input to the idl command. For example: $ pipe type my_filename.idl | idl -stdin 5 -version - version Displays the current version of the IDL compiler. 5 -v -v Prints informational messages (verbose mode) on the screen while the compiler is running. 5 -no_warn -no_warn Suppresses compiler warning messages. 5 -confirm -confirm Displays all the idl command arguments you chose, but does not compile the source IDL file. If you use this with the -v argument, informational messages about how the compiler behaves if you do not use -confirm are displayed but no corresponding actions are performed. 5 -template_client -template_client filename Requests that the IDL compiler generate a C source file containing a template implementation of each routine that must appear in the client application to use the specified IDL interface. If you do not specify an extension for filename, the compiler assigns the file extension .c. 5 -template_manager -template_manager filename Requests that the IDL compiler generate a C source file containing a template implementation of each routine and operation that must appear in the manager module of the server side of an application to use the specified IDL interface. If you do not specify an extension for filename, the compiler assigns the file extension .c. 5 -trace -trace value Enables event logging. You can specify one of the following values for the value argument: all Log all events. none Disable all previously specified trace options. calls Log events relating to start and end of all RPC calls. context Log events relating to context handle creation, deletion, and rundown. errors Log errors. misc Log all miscellaneous events. log_manager Enable command interface support which allows modification at runtime of event logging options. 5 -lang -lang {c, cxx, fortran} Allows you to select a programming language. If you are generating stubs and include files for application code written in C++, you must specify cxx as the language of choice when you compile the application's IDL file. When appropriate, you can extend the class hierarchy and derive other classes from this one, to implement some or all interface operations. The C++ compiler gives a warning if any functions in the interface class have not been implemented. Avoid overwriting the manager class header file by using the -no_cxxmgr argument in conjunction with the -lang cxx argument. If you are generating stubs and include files for application code written in FORTRAN, you must specify FORTRAN as the language of choice when you compile the application's IDL file. If you do not specify -lang fortran or -lang cxx, the default value is the C programming language or -lang c. 5 -no_cxxmgr -no_cxxmgr Prevents the compiler from overwriting the manager class header file. Use this argument in conjunction with the -lang cxx argument if you implement application-specific C++ code in the manager class header file. 4 EXAMPLES 1. Invoke the IDL compiler to compile the interface definition file test.idl and keep the generated C source modules. Only server files are generated. The server stub default filename is overridden by creating a file named test_ss.c for the server stub module. $ idl test.idl -keep c_source -client none -sstub test_ss.c 2. Invoke the IDL compiler to compile the interface definition file test.idl, but do not run the C preprocessor. The manager entry point vector is not defined in the generated server stub module. The IDL compiler searches the parent directory of the current directory for any IDL files that test.idl could import. The generated output files are located in the output subdirectory under the current directory. $ idl test.idl -no_cpp -no_mepv -I.. -out ./output 3 rpclm NAME rpclm - Starts the command line interface to the RPC Event Logger Log Manager SYNOPSIS rpclm "listening event string binding" ARGUMENTS inquire Inquire about the currently logged events and determine the name of the active log file. log Specify additional events to log: all, none, calls, context, errors, or misc. unlog Disable logging of the specified event types: all, none, calls, context, errors, or misc. file Change the output device or file to which events are logged. quit Terminate the rpclm session. help Display a description of the rpclm command interface commands. 4 DESCRIPTION The RPC Event Logger records information in an event log about application execution. After enabling the Log Manager when you compile the interface, you can use the Log Manager command line options to modify event logging parameters at runtime. Follow these steps to enable the RPC Log Manager: 1. Use the -trace log_manager option at IDL compilation time. 2. Create the RPC_LOG_FILE symbol and assign it to a file name or to screen output. 3. Execute the client or server process, or both. 4. When the first call is made to an interface compiled with the -trace option, a listening event will be generated into the event log. Invoke the rpclm command interface by specifying the string binding from the listening event. EXAMPLES To enable the Log Manager, use the following syntax: idl file-name.idl -trace log_manager To invoke the rpclm command interface, specify the string binding from a listening event, as in the following example: rpclm ncacn_ip_tcp:16.31.48.144[3820] The symbol rpclm is defined in the DCE$DEFINE_OPTIONAL_COMMANDS command procedure. This command file can be found in SYS$COMMON:[DCE$LIBRARY]. RELATED INFORMATION "HP DCE for OpenVMS Alpha and OpenVMS I64 Product Guide" 3 uuidgen NAME uuidgen - Generates a Universal Unique Identifier (UUID) SYNOPSIS uuidgen [argument] ... Arguments -c Allows you to supply an existing UUID that uuidgen then outputs in the format you specify. This option is especially useful in combination with the -s option for converting an existing UUID into a C structure. You must specify the -c option at the end of the uuidgen command line; all options that follow -c are ignored. -i Produces an Interface Definition Language (IDL) file template and includes the generated UUID string in the template. -o filename Redirects the generated UUID string to the file you specify. -s Generates a UUID string as an initialized C structure. -v Displays the version number of the UUID generator, but does not generate a UUID. -h Displays information about the uuidgen command arguments. The arguments -h and -? can be used interchangeably. -? Displays information about the uuidgen command arguments. The arguments -? and -h can be used interchangeably. -n number_of_uuid_strings Generates a specified number of UUID strings. DESCRIPTION The uuidgen command creates a UUID string that you assign to an object to uniquely identify it. One such use is in the UUID interface attribute of an IDL interface definition. The format for representing a UUID string consists of eight hexadecimal digits followed by a dash, followed by three groups of four hexadecimal digits separated by dashes, followed by a dash and twelve hexadecimal digits: 01234567-89ab-cdef-0123-456789abcdef The symbol uuidgen is defined in the DCE$DEFINE_OPTIONAL_COMMANDS command procedure. This command file can be found in SYS$COMMON:[DCE$LIBRARY]. FILES The locations of files have the following pathnames: SYS$SYSTEM:DCE$UUIDGEN.EXE UUID Generator EXAMPLES 1. Generate a UUID string: $ uuidgen 23c67e00-71b6-11c9-9dfc-08002b0ecef1 2. Generate a partial template, containing a generated UUID string, to be used to develop an interface definition: $ uuidgen -i [ uuid(828bf780-71b6-11c9-b5a8-08002b0ecef1), version (1.0) ] interface INTERFACENAME { } 3. Convert a UUID string from the old-style format to the new format: $ uuidgen -t 34DC23469EAF.AB.A2.01.7C.5F.2C.ED.A3 34dc2346-9eaf-0000-aba2-017c5f2ceda3 4. Generate four UUID strings: $ uuidgen -n 4 612c0b00-71b8-11c9-973a-08002b0ecef1 612c0b01-71b8-11c9-973a-08002b0ecef1 612c0b02-71b8-11c9-973a-08002b0ecef1 612c0b03-71b8-11c9-973a-08002b0ecef1 5. Convert a UUID into a C structure: $ uuidgen -s -c 1251ace6-93al-11cd-95ad-0800097086e4 = { /* 1251ace6-93al-11cd-95ad-0800097086e4 */ 0x1251ace6, 0x93al, 0x11cd, 0x95, 0xad {0x08, 0x00, 0x09, 0x70, 0x86, 0xe4} }; RELATED_INFORMATION Commands: uuidgen. 4 UUIDGEN_DCL_Command_Interface This section provides DCL syntax for the UUID generation utility. Except where noted, DCL commands are equivalent to the universal command syntax documented in the uuidgen section of the OSF DCE Application Development Reference. See the Reference documentation for a complete description of the universal command syntax interface to the UUID generation utility. Users may choose to use either the universal interface to the UUID generation utility or the DCL-style alternative. NAME IDENTIFIER/TRANSLATE - Translates a DCE RPC Version UUID to a DCE RPC UUID. SYNOPSIS IDENTIFIER/TRANSLATE old-style-uuid [qualifier]... QUALIFIERS /OUTPUT=file /OUTPUT=SYS$OUTPUT (default) This qualifier, used with a file name, directs output to a file. If you do not specify a file name, the converted UUID goes to SYS$OUTPUT, generally your display terminal. NAME IDENTIFIER/GENERATE - Generates one or more DCE RPC UUIDs. SYNOPSIS IDENTIFIER/GENERATE [qualifier] QUALIFIERS /FORMAT [=option] Specify one or more of the following options. STRING (default) STRING Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx This is a raw UUID in its readable form. IDL IDL Format: [uuid(xxxxxxxx-xxxx-xxxx-xxxx- xxxxxxxxxxxx)] This is a UUID as it appears syntactically in an RPC interface definition. STRUCT STRUCT Format: This is an initialized C structure declaration, which can be included in C code that is used with DCE RPC. /COUNT=n This qualifier specifies the number of UUID strings to be generated. If you do not specify a number for n, the number 1 is used by default. /OUTPUT=file /OUTPUT=SYS$OUTPUT (default) This qualifier, used with a file name, directs output to a file. If you do not specify a file name, the converted UUID goes to SYS$OUTPUT, generally your display terminal. 3 rpccp NAME rpccp - Starts the RPC control program SYNOPSIS rpccp [rpccp-command] NOTES This facility is superceded by the DCE control program (dcecp) for OSF DCE version 1.1. A server entry equates to an NSI binding attribute and, optionally, an object attribute; a group equates to an NSI group attribute; and a profile equates to an NSI profile attribute. Typically, each server's entries, groups, and profiles reside in distinct name service entries. NOTES With the exception of the rpccp_help subcommand, this command is replaced at Revision 1.1 by the dcecp command. This command may be fully replaced by the dcecp command in a future release of DCE, and may no longer be supported at that time. DESCRIPTION The RPC control program (RPCCP) provides a set of commands for managing name service use for RPC applications and for managing the endpoint map. You can use control program commands from within the control program or from the system prompt (represented here as a $). To use the control program commands from inside the control program, Start and enter the control program using the rpccp command alone, without any argument. The control program then displays the control program prompt (rpccp>), as follows: $ rpccp rpccp> You can then enter any control program command, for example: rpccp> show entry /.:/LandS/anthro/pr_server_node3 You leave the control program and return to the system prompt using the exit or quit command. If you enter invalid input, the control program displays the valid commands. To use the control program commands from the system prompt, enter the rpccp command with an internal command of the control program as the first argument. You can do this either interactively or in a command procedure. For example, you can enter the show entry command as follows: $ rpccp show entry /.:/LandS/anthro/pr_server_node3 RELATED INFORMATION Commands: dcecp add element add entry add mapping add member export import remove element remove entry remove group remove mapping remove member remove profile show entry show group show mapping show profile show server unexport 4 ARGUMENTS Arguments and Options Except for the exit and quit commands, rpccp commands have one or more options. Each option is identified by a - (dash) followed by a letter; for example, -s. Some options require arguments. Commands that access NSI operations also require the name of a name service entry as an argument. The order of arguments and the entry-name option is arbitrary; for example, the following placements of arguments and options are equivalent: rpccp> add element /.:/LandS/anthro/mis_node_2 \ > -i ec1eeb60-5943-11c9-a309-08002b102989,1.0 rpccp> add element -i ec1eeb60-5943-11c9-a309-08002b102989,1.0 \ > /.:/LandS/anthro/mis_node_2 rpccp-command Specifies one of the following control program commands: add element Adds an element to a profile in a name service entry; if the specified entry does not exist, creates the entry. add entry Adds an entry to the name service database. add mapping Adds or replaces server address information in the local endpoint map. add member Adds a member to a group in a name service entry; if the specified entry does not exist, creates the entry. exit Leaves the RPC control program. export Exports binding information for an interface identif- ier, object UUIDs, or both to a server entry; if the specified entry does not exist, creates the entry. help Displays a list of commands or the possible options of a specified command. import Imports binding information and an object UUID from a server entry. quit Leaves the RPC control program. remove element Removes selected elements from a profile. remove entry Removes an entry from the name service database. remove group Removes all group members and the group from the specified entry. remove mapping Removes specified elements from the local endpoint map or from the endpoint map of a specified remote host. remove member Removes a selected member from a group. remove profile Removes all profile elements and the profile from the specified entry. show entry Shows the NSI attributes of an entry. show group Shows the members of a group. show mapping Shows the elements of the local endpoint map. show profile Shows the elements of a profile. show server Shows the binding information, interface identifier, and object UUIDs in a server entry. unexport Removes binding information, interface identifiers,and object UUIDs from a server entry. 5 add_element NAME add element - Adds an element to a profile in a name service entry; if the specified entry does not exist, creates the entry. SYNOPSIS rpccp add element profile-entry-name -m member {-d | -i if-id [-p priority]} [-a annotation] [-s syntax ] OPTIONS -m Defines a member name for the profile element to be added (required). -d Performs the add element operation on the default profile element. With the -d option, the -i and -p options are ignored. -i Defines an interface identifier for the profile element to be added. Only one interface can be added in a single operation. An interface identifier is required, unless the default profile element is being added. With the -d option, the -i option is ignored. The value has the following form: interface-uuid,major-version.minor-version The UUID is a hexadecimal string and the version numbers are a decimal string, for example: -i ec1eeb60-5943-11c9-a309-08002b102989,3.11 Leading zeros in version numbers are ignored. -p Defines a search priority for the new profile element. The priority value is in the range 0 to 7, with zero having the highest priority. When a default element is added (with the -d option), the -p option is ignored.By default, a nondefault element is assigned a priority value of zero. -a Defines an annotation string for the profile element. Note that the shell supports quotation marks around the annotation field of profile elements, which allows you to include internal spaces in an annotation; the control program does not. To specify or refer to annotations from within the control program, limit each annotation to an unbroken alphanumeric string; for example, CalendarGroup. To refer to annotations from the system prompt, do not incorporate quotation marks into any annotation. -s Indicates the name syntax of the entry name (optional). The only value for this option is the dce name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the -s option is unnecessary. ARGUMENTS profile-entry-name Specifies the entry name of the target profile. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. DESCRIPTION The add element command adds an element to a profile in a name service entry. The name of the entry containing the profile and the entry name of the profile member in the new element are required. The entry of a profile may have been created previously (by either the add entry or add element command). But, if the specified entry does not exist, the add element command tries to create the entry. A profile element is a database record containing the following fields: Interface identifier This is the primary search key. The interface identifier consists of the interface UUID and the interface version numbers. Member name The entry name of one of the following kinds of name service entries: + A server entry for a server offering the requested RPC interface and object + A group corresponding to the requested RPC interface + A profile Priority value The priority value (0 (zero) is the highest priority; 7 is the lowest) is designated by the creator of a profile element to help determine the order for using the element. NSI search operations select among like priority elements at random. For the rpccp add element command, the default is 0. Annotation string The annotation string enables you to identify the purpose of the profile element. The annotation can be any textual information, for example, an interface name associated with the interface identifier or a description of a service or resource associated with a group. The annotation string is not a search key for the import or lookup operations. Privilege Required You need both read permission and write permission to the CDS object entry (the target profile entry). If the entry does not exist, you also need insert permission to the parent directory. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES The following command adds an element to the cell profile, /cell-profile, in the local cell: $ rpccp rpccp> add element \ > -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \ > -m /.:/Calendar_profile \ > -a RefersToCalendarGroups \ > /.:/cell-profile The following control program commands start the control program, set up a user profile associated with the cell profile as its default element, and add a user-specific element for the Calendar V1.1 interface, as follows: $ rpccp rpccp> add element /.:/LandS/anthro/molly_o_profile \ > -d -m /.:/cell-profile rpccp> rpccp> add element /.:/LandS/anthro/molly_o_profile \ > -m /.:/LandS/anthro/Calendar_group \ > -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \ > -a Calendar_Version 1.1_Interface rpccp> The added profile element contains the global name of the member (specified using its cell-relative name, /.:/LandS/anthro/Calendar_group) and the RPC interface identifier for the Calendar Version 1.1 interface. RELATED INFORMATION Commands: remove element remove profile show profile 5 add_entry NAME add entry - Adds a name service entry to the name service database SYNOPSIS rpccp add entry entry-name [-s syntax] OPTIONS -s Indicates the name syntax of the entry name (optional). The only value for this option is the dce name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the -s option is unnecessary. ARGUMENTS entry-name Specifies the name of the target name service entry. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. DESCRIPTION The add entry command adds an unspecialized entry to the name service database. The name of the entry is required. The new entry initially contains no NSI attributes. This command creates a general name service entry for an application or user. The application or user can later use the export, add element, and add member commands to make the generic entry into a server entry, a group, or a profile (or a combination), as follows: + For a server entry, specify the new entry as the target entry for the rpccp export command. + For a group, specify the new entry as the target group for the rpccp add member command. + For a profile, specify the new entry as the target profile for the rpccp add element command. The add entry command enables administrators to add entries for users who lack the required permissions. If you have the permissions required by the add entry command, you can also add an entry using an export, add member, or add element command; if the entry you specify does not exist, the command creates the entry. Privilege Required To add an entry, you need insert permission to the parent directory and both read permission and write permission to the CDS object entry (the target name service entry). NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES The following commands start RPCCP and add an unspecialized entry to the name service database: $ rpccp rpccp> add entry \ > /.:/LandS/anthro/Cal_host_2 The following command operates from the system prompt to add an unspecialized entry to the name service database: $ rpccp add entry \ > /.:/LandS/anthro/Cal_host_3 RELATED INFORMATION Commands: remove entry show entry 5 add_mapping NAME add mapping - Adds or replaces server address information in the local endpoint map SYNOPSIS rpccp add mapping -b string-binding -i interface-identifier [-a annotation-string] [-o object-uuid] [-N] OPTIONS -b Specifies a string representation of a binding over which the server can receive remote procedure calls. At least one binding is required. The value has the form of an RPC string binding, without an object UUID, for example: -b ncadg_ip_udp:63.0.2.17[5347] Note that depending on your system, string binding delimiters such as brackets ([ ]) may need to be preceded by an escape symbol (\) or placed within quotation marks (' ' or " "). Requirements vary from system to system, and you must conform to the usage rules of a system. -i Specifies an interface identifier to register with the local endpoint map. An interface identifier is required. Only one interface can be added (i.e., registered) in a single operation. The interface identifier has the following form: interface-uuid,major-version.minor-version The UUID is a hexadecimal string and the version numbers are decimal strings, for example: -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 Leading zeros in version numbers are ignored. -a Specifies a character string comment to be applied to each cross product element that is added to the local endpoint map. The string can be up to 64 characters long, including the NULL terminating character. The string is used by applications for informational purposes only. The RPC runtime does not use this string to determine which server instance a client communicates with, or for enumerating endpoint map elements. -o Defines an object UUID that further determines the endpoint map elements that are removed (optional). Each add mapping command accepts up to 32 -o options. The UUID is a hexadecimal string, for example: -o 3c6b8f60-5945-11c9-a236-08002b102989 -N Specifies that existing elements in the local host's endpoint map should not be replaced when the new information is added. DESCRIPTION The add mapping command adds to, replaces, or adds server address information to the local endpoint map. Each element in the local endpoint map logically contains the following: + Interface ID, consisting of an interface UUID and versions (major and minor) + Binding information + Object UUID (optional) + Annotation (optional) This command should be used without the -N option when only a single instance of the server in question runs on the server's host. Do not use the -N option if no more than one server instance on the host ever offers the same interface UUID, object UUID, and protocol sequence. When local endpoint map elements are not replaced, obsolete elements accumulate each time a server instance stops running without explicitly unregistering its endpoint map information. Periodically, the RPC Daemon (DCED) will identify these obsolete elements and remove them. However, during the interval between these removals, the presence of the obsolete elements increases the chance that clients will receive endpoints to nonexistent servers. The clients will then waste time trying to communicate with these servers before giving up and obtaining another endpoint. Allowing DCED to replace any existing local endpoint map elements (by not specifying -N) reduces the chance of this happening. For example, suppose an existing element in the local endpoint map matches the interface UUID, binding information exclusive of the endpoint, and object UUID of an element this routine provides. The routine changes the endpoint map according to the elements' interface major and minor version numbers. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES The following command operates from the system prompt to add a map element to the local endpoint map. The command adds the map element that contains the specified interface identifier, server address (specified as a string binding), and object UUIDs. $ rpccp add mapping -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \ -b ncadg_ip_udp:63.0.2.17[5347] \ -o 005077d8-8022-1acb-9375-10005a4f533a \ -o 001bc29a-8041-1acb-b377-10005a4f533a \ -a 'Calendar version 1.1' $ The previous command adds the following elements: interface ID ec1eeb60-5943-1169-a309-08002b102989,1.1 string binding ncadg_ip_udp:63.0.2.17[5347] objects 005077d8-8022-1acb-9375-10005a4f533a 001bc29a-8041-1acb-b377-10005a4f533a annotation Calendar version 1.1 RELATED INFORMATION Commands: export remove mapping show mapping show server Subroutines: rpc_ep_register rpc_ep_register_no_replace 5 add_member NAME add member - Adds a member to a group in a name service entry; if the specified entry does not exist, creates the entry SYNOPSIS rpccp add member group-entry-name -m member [-s syntax] OPTIONS -m Declares the name of a member to be added to the specified group entry (required). You can add only one member at a time. -s Indicates the name syntax of the entry name (optional). The only value for this option is the dce name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the -s option is unnecessary. ARGUMENTS group-entry-name Specifies the name of the target group. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. DESCRIPTION The add member command adds a member to a group in a name service entry. The name of the entry containing the group and the name of the new group member are required. The entry of a group may have been created previously (by either the add entry or add member command). If the specified entry does not exist, the add member command tries to create the entry. Privilege Required You need both read permission and write permission to the CDS object entry (the target group entry). If the entry does not exist, you also need insert permission to the parent directory. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES The following commands run RPCCP and add the member /.:/LandS/anthro/Cal_host_3 to the group /.:/LandS/anthro/Calendar_group: $ rpccp rpccp> add member \ > -m /.:/LandS/anthro/Cal_host_3 \ > /.:/LandS/anthro/Calendar_group RELATED INFORMATION Commands: remove group remove member show group 5 export NAME export - Exports binding information for an interface identifier or object UUIDs or both to a server entry; if the specified entry does not exist, creates the entry SYNOPSIS rpccp export entry-name {-i if-id -b string-binding [-b string-binding...] -o object-uuid [-o object-uuid...] | -i if-id -b string-binding [-b...] | -o object-uuid [-o object-uuid...] } [-s syntax ] OPTIONS -i Declares the interface identifier of an RPC interface. The export command operates on only one -i option; if you enter more than one, the command ignores all but the last interface identifier. If you specify an interface identifier, you must specify at least one -b option. The -i and -o options can occur together or separately, but one of them is necessary. The interface identifier takes the following form: interface-uuid,major-version.minor-version The version numbers are optional, but if you omit a version number, the value defaults to 0. The UUID is a hexadecimal string and the version numbers are decimal strings, for example: -i ec1eeb60-5943-11c9-a309-08002b102989,3.11 Leading zeros in version numbers are ignored. -b Declares a string binding (optional). To use this option, you must also specify an interface identifier (using the -i option). Each command accepts up to 32 -b options. The value has the form of an RPC string binding, without an object UUID. The binding information contains an RPC protocol sequence, a network address, and sometimes an endpoint within brackets (rpc-prot-seq:network-addr[endpoint]). For a well-known endpoint, include the endpoint in the string binding, for example: -b ncadg_ip_udp:63.0.2.17[5347] For a dynamic endpoint, omit the endpoint from the string binding, for example: -b ncacn_ip_tcp:16.20.15.25 Note that depending on your system, string binding delimiters such as brackets ([ ]) may need to be preceded by an escape symbol (\) or placed within quotation marks (' ' or " "). Requirements vary from system to system, and you must conform to the usage rules of a system. -o Declares the UUID of an object. Each export command accepts up to 32 -o options. The -i and -o options can occur together or separately, but one of them is necessary. The UUID is a hexadecimal string, for example: -o 3c6b8f60-5945-11c9-a236-08002b102989 -s Indicates the name syntax of the entry name (optional). The only value for this option is the dce name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the -s option is unnecessary. ARGUMENTS entry-name Specifies the name of the target name service entry. Usually, the target is a server entry. However, objects also can be exported (without an interface identifier or any binding information) to a group or a profile. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. DESCRIPTION The export command places binding information and an interface identifier, object UUIDs, or both into a server entry, or the command object UUIDs into a group's entry. The export command searches the name service database for the entry with the specified entry name. If the entry exists, the command uses it; otherwise, the command tries to create a new name service entry using the specified entry name. Minimally, the command requires the name of the entry and either an identifier and binding string or an object. If the specified entry does not exist, the export command tries to create the entry. Privilege Required You need both read permission and write permission to the CDS object entry (the target name service entry). If the entry does not exist, you also need insert permission to the parent directory. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES This example shows a control program export command that is stored in a file for later execution from the system prompt. The command exports two objects and an interface with two string bindings to the server entry /.:/LandS/anthro/Cal_host_3 in the local cell: # file to export Calendar 1.1 at installation time rpccp export \ -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \ -b ncacn_ip_tcp:16.20.15.25 \ -b ncadg_ip_udp:63.0.2.17 \ -o 30dbeea0-fb6c-11c9-8eea-08002b0f4528 \ -o 16977538-e257-11c9-8dc0-08002b0f4528 \ /.:/LandS/anthro/Cal_host_3 The following example shows the use of a user-defined logical name as an interface identifier, to facilitate entering an export command interactively (in this case, from inside the control program). The initial DCL command sets up a logical name Calendar_1_1, which represents the interface identifier of an RPC interface. The rpccp command then starts the control program, and the export command exports the Calendar interface and two string bindings to the server entry /.:/LandS/anthro/Cal_host_2 in the local cell, as follows: $ define Calendar_1_1 ec1eeb60-5943-11c9-a309-08002b102989,1.1 $ rpccp rpccp> export -i Calendar_1_1 \ > -b ncacn_ip_tcp:16.20.15.25 \ > -b ncadg_ip_udp:63.0.2.17 \ > /.:/LandS/anthro/Cal_host_2 The following example shows the use of user-defined logical names for object UUIDs to facilitate entering an export command interactively (in this case, from inside the control program). The initial DCL commands set up the logical names LUKE_CAL and JOSH_CAL, which represent personal calendars that are accessible as objects to an RPC server. The rpccp command then starts the control program, and the export command exports the two objects to the server's entry /.:/LandS/anthro/Cal_host_2 in the local cell: $ define LUKE_CAL 30dbeea0-fb6c-11c9-8eea-08002b0f4528 $ define JOSH_CAL 16977538-e257-11c9-8dc0-08002b0f4528 $ rpccp rpccp> export -o LUKE_CAL -o JOSH_CAL \ > /.:/LandS/anthro/Cal_host_2 RELATED INFORMATION Commands: import show server unexport 5 help NAME help - Displays a list of commands or the options of a specified command SYNOPSIS rpccp help [rpccp-command] ARGUMENTS rpccp-command Specifies one of the following control commands: add element add entry add member exit export import quit remove element remove entry remove group remove mapping remove member remove profile show entry show group show mapping show profile show server unexport DESCRIPTION The help command displays information about the RPCCP command set or the options and argument associated with a specific command. NOTE This command may be replaced in future releases by the dcecp command, and may no longer be supported at that time. EXAMPLES The following command operates from the system prompt to display the internal commands of the control program: $ rpccp help The following commands start the control program and display the syntax of the remove entry command: $ rpccp rpccp> help remove entry RELATED INFORMATION Commands: add element add entry add member export import remove element remove entry remove group remove mapping remove member remove profile rpccp show entry show group show mapping show profile show server unexport 5 import NAME import - Imports binding information and an object UUID from a server entry SYNOPSIS rpccp import starting-entry-name -i if-id [-v versions] [-e] [-n [integer]] [-o object-uuid] [-s syntax] [-u] OPTIONS -i Defines an interface identifier to be imported (required). You can import only one interface at a time. The value has the following form: interface-uuid,major-version.minor-version The UUID is a hexadecimal string and the version numbers are decimal strings, for example: -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 Leading zeros in version numbers are ignored. -v Indicates how a specified interface version is used (optional). If it is used without the -i option, the -v option is ignored. The possible combinations of versions for the -v option and their actions are as follows: Versions Action ________________________________________________ all The interface version is ignored. exact Both the major and minor versions must match the specified versions. compatible The major version must match the specified version, and the minor version must be greater than or equal to the specified version. major_only The major version must match the specified version; the minor ver- sion is ignored. upto The major version must be less than or equal to that specified. If the major versions are equal, the minor version must be less than or equal to that specified. ________________________________________________ If the -v option is absent, the command shows compatible version numbers. -e Shows the name of the entry where the binding is found (optional). -n Declares that the import operation is to continue until no more potential bindings are found (optional). Providing a numeric value to this option restricts the number of imported bindings. If you omit the number, only one binding is imported. If repeated, this operation may return the same binding. For example, -n imports all available bindings, and -n 5 imports up to five bindings. Note that the imported bindings are displayed as string bindings. -o Declares the UUID of an object to be imported (optional). Only one UUID can occur in a single operation. If an object is specified, the import operation limits its search to server entries that contain both the specified interface identifier and object UUID when searching for a potential binding. Without the -o option, the import operation ignores object UUIDs. The UUID is a hexadecimal string, for example: -o 3c6b8f60-5945-11c9-a236-08002b102989 -s Indicates the name syntax of the entry name (optional). The only value for this option is the dce name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the -s option is unnecessary. -u Updates the local CDS cache copy of name service data (optional). Name service data is cached locally on each machine in a cell. If an rpccp inquiry can be satisfied by data in the local CDS cache, this cached data is returned. Locally cached copies of name service data might not include a recent CDS update, however. If the required data is not available in the local CDS cache, rpccp goes to a CDS server(s) to retrieve the required data. rpccp then updates the local CDS cache. Using the -u option bypasses the local cache, allowing rpccp to go directly to a CDS server for the inquiry. rpccp then updates the local CDS cache. ARGUMENTS starting-entry-name Indicates the name of the server entry where the import operation starts. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. DESCRIPTION The import command imports binding information and an RPC object UUID for a specific RPC interface from a server entry. The name of the entry and the interface identifier are required. The entry name can refer to a server entry, a group, or a profile. Privilege Required You need read permission to the specified CDS object entry (the starting name service entry) and to any CDS object entry in the resulting search path. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES The following commands run RPCCP and import an interface and object: $ rpccp rpccp> import -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \ > -o 30dbeea0-fb6c-11c9-8eea-08002b0f4528 \ > /.:/LandS/anthro/Cal_host_3 RELATED INFORMATION Commands: export show server unexport 5 remove_element NAME remove element - Removes selected elements from a profile SYNOPSIS rpccp remove element profile-entry-name {-d | -i if-id -m member | -a annotation} [-s syntax] OPTIONS -d Removes the default profile element. With the -d option, the -a, -i, and -m options are ignored. -i Defines an interface identifier for the profile element to be removed for a member specified with the -m option. Only one interface and member pair can be removed in a single operation. If you supply multiple instances of the -i option, the command uses the final instance. The -i and -m options take precedence over the -a option. However, if the default profile element is specified (by the -d option), the -i and -m options are ignored. The interface identifier value has the following form: interface-uuid,major-version.minor-version The UUID is a hexadecimal string and the version numbers are decimal strings, for example: -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 Leading zeros in version numbers are ignored. -m Defines a member name for the profile element to be removed. This option is required if the interface identifier is specified. Only one interface and member can be removed in a single operation. If you supply multiple instances of the -m option, the command uses the final instance. -a Removes all elements whose annotation fields match the specified annotation; in the presence of -d option or -i and -m options, the -a option is ignored. Note that the shell supports quotation marks around the annotation field of profile elements, which allows you to include internal spaces in an annotation; the control program does not. To specify or refer to annotations from within the control program, limit each annotation to an unbroken alphanumeric string; for example, CalendarGroup. To refer to annotations from the system prompt, do not incorporate quotation marks into any annotation. -s Indicates the name syntax of the entry name (optional). The only value for this option is the dce name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the -s option is unnecessary. ARGUMENTS profile-entry-name Indicates the name of the target profile. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. DESCRIPTION The remove element command removes an element from a profile in the name service database. For a description of the fields in a profile element, see add entry. The remove element command requires the entry name of the profile. The command also requires one of the following options: -d The default profile option takes precedence over the other two options. -i interface-id -m member-name An interface and member pair takes precedence over the -a option. -a annotation-string The annotation option takes effect only if neither the -d or -i option is specified. Privilege Required You need read permission and write permission to the CDS object entry (the target profile entry). NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES The initial DCL command sets up a logical name Calendar_1_1, which represents the interface identifier of an RPC interface. The control program commands set up a logical name for the interface identifier of the Calendar Version 1.1 RPC interface, run RPCCP, and remove an element from a profile, as follows: $ define Calendar_1_1 ec1eeb60-5943-11c9-a309-08002b102989,1.1 $ rpccp rpccp> remove element -i Calendar_1_1 \ > -m /.:/LandS/anthro/Calendar_group \ > /.:/LandS/anthro/molly_o_profile RELATED INFORMATION Commands: add element remove profile show profile 5 remove_entry NAME remove entry - Removes a name service entry from the name service database SYNOPSIS rpccp remove entry entry-name [-s syntax] OPTIONS -s Indicates the name syntax of the entry name (optional). The only value for this option is the dce name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the -s option is unnecessary. ARGUMENTS entry-name Indicates the name of the target name service entry. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. DESCRIPTION The remove entry command removes an entry from the name service database. The name of the entry is required. Privilege Required You need read permission to the CDS object entry (the target name service entry). You also need delete permission to the CDS object entry or to the parent directory. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES The following commands run RPCCP and remove the entry /.:/LandS/anthro/Cal_host_2 from the local cell of the name service database: $ rpccp rpccp> remove entry /.:/LandS/anthro/Cal_host_2 RELATED INFORMATION Commands: add entry show entry 5 remove_group NAME remove group - Removes all group members and the group from the specified name service entry SYNOPSIS rpccp remove group group-entry-name [-s syntax] OPTIONS -s Indicates the name syntax of the entry name (optional). The only value for this option is the dce name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the -s option is unnecessary. ARGUMENTS group-entry-name Indicates the name of the target group. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. DESCRIPTION The remove group command removes a group from the name service database. The group need not be empty. The entry name of the group is required. Privilege Required You need write permission to the CDS object entry (the target group entry). NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES The following commands run RPCCP and remove the group from the name service entry /.:/LandS/anthro/Calendar_group: $ rpccp rpccp> remove group /.:/LandS/anthro/Calendar_group RELATED INFORMATION Commands: add member remove member show group 5 remove_mapping NAME remove mapping - Removes specified elements from the local endpoint map SYNOPSIS rpccp remove mapping -b string-binding -i interface-identifier [-o object-uuid] OPTIONS -b Specifies a string representation of a binding over which the server can receive remote procedure calls. At least one binding is required. The value has the form of an RPC string binding, without an object UUID, for example: -b ncadg_ip_udp:63.0.2.17[5347] Note that depending on your system, string binding delimiters such as brackets ([ ]) may need to be preceded by an escape symbol (\) or placed within quotation marks (' ' or " "). Requirements vary from system to system, and you must conform to the usage rules of a system. -i Specifies an interface identifier to remove from the local endpoint map. An interface identifier is required. Only one interface can be removed in a single operation. The interface identifier has the following form: interface-uuid,major-version.minor-version The UUID is a hexadecimal string and the version numbers are decimal strings, for example: -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 Leading zeros in version numbers are ignored. -o Defines an object UUID that further determines the endpoint map elements that are removed (optional). Each remove mapping command accepts up to 32 -o options. The UUID is a hexadecimal string, for example: -o 3c6b8f60-5945-11c9-a236-08002b102989 DESCRIPTION The remove mapping command removes server address information from the local endpoint map. Each element in the local endpoint map logically contains the following: + Interface ID, consisting of an interface UUID and versions (major and minor) + Binding information + Object UUID (optional) + Annotation (optional) This command requires one interface identifier (the -i option); at least one string binding (the -b option); and optionally, one or more object UUIDs (the -o option). Each instance of the command accepts from 1 to 32 -b options and from 0 to 32 -o options. The options work together to delimit the elements to be removed from the target endpoint map. The command removes any map element that contains the specified interface identifier, a specified string binding, and a specified object UUID (if any). NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES The following command operates from the system prompt to remove a map element from the local endpoint map. The command removes only the map element that contains the specified interface identifier, server address (specified as a string binding), and object UUID. $ rpccp remove mapping \ > -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \ > -b ncadg_ip_udp:16.20.16.64[3424] \ > -o 30dbeea0-fb6c-11c9-8eea-08002b0f4528 $ RELATED INFORMATION Commands: add mapping show mapping show server 5 remove_member NAME remove member - Removes a specified member from a group SYNOPSIS rpccp remove member group-entry-name -m member [-s syntax] OPTIONS -m Declares the entry name of the group member to be removed (required). -s Indicates the name syntax of the entry name (optional). The only value for this option is the dce name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the -s option is unnecessary. ARGUMENTS group-entry-name Indicates the name of the target group. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. DESCRIPTION The remove member command removes a specified member from a specified group. Privilege Required You need read permission and write permission to the CDS object entry (the target group entry). NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES The following commands run RPCCP and remove the member /.:/LandS/anthro/Cal_host_2 from the group /.:/LandS/dept/Calendar_group: $ rpccp rpccp> remove member \ > -m /.:/LandS/anthro/Cal_host_2 \ > /.:/LandS/anthro/Calendar_group The following command removes the member /.:/LandS/anthro/Cal_host_3 from the group /.:/LandS/anthro/Calendar_group: $ rpccp remove member \ > -m /.:/LandS/anthro/Cal_host_3 \ > /.:/LandS/anthro/Calendar_group RELATED INFORMATION Commands: add member remove group show group 5 remove_profile NAME remove profile - Removes all profile elements and the profile from the specified name service entry SYNOPSIS rpccp remove profile profile-entry-name [-s syntax] OPTIONS -s Indicates the name syntax of the entry name (optional). The only value for this option is the dce name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the -s option is unnecessary. ARGUMENTS profile-entry-name Indicates the name of the target profile. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. DESCRIPTION The remove profile command removes a profile (and all of its elements) from the name service database. The entry name of the profile is required. Privilege Required You need write permission to the CDS object entry (the target profile entry). NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES The following commands run RPCCP and remove the profile named /.:/LandS/anthro/molly_o_profile: $ rpccp rpccp> remove profile /.:/LandS/anthro/molly_o_profile RELATED INFORMATION Commands: add element remove element show profile 5 show_entry NAME show entry - Shows the NSI attributes of a name service entry SYNOPSIS rpccp show entry entry-name [-i if-id] [-s syntax] [-u] OPTIONS -i Selects a specified interface identifier (optional). Only elements containing that identifier are shown. The interface identifier value has the following form: interface-uuid,major-version.minor-version The UUID is a hexadecimal string and the version numbers are decimal strings, for example: -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 Leading zeros in version numbers are ignored. -s Indicates the name syntax of the entry name (optional). The only value for this option is the dce name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the -s option is unnecessary. -u Updates the local CDS cache copy of name service data (optional). Name service data is cached locally on each machine in a cell. If an rpccp inquiry can be satisfied by data in the local CDS cache, this cached data is returned. Locally cached copies of name service data might not include a recent CDS update, however. If the required data is not available in the local CDS cache, rpccp goes to a CDS server(s) to retrieve the required data. rpccp then updates the local CDS cache. Using the -u option bypasses the local cache, allowing rpccp to go directly to a CDS server for the inquiry. rpccp then updates the local CDS cache. ARGUMENTS entry-name Indicates the name of the target name service entry. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. DESCRIPTION The show entry command shows the NSI attributes of a name service entry. The name of the entry is required. Note that this operation shows all of the compatible bindings for a given interface. The show entry command shows the same list of string bindings as the import operation returns for the specified entry. This list includes all string bindings that refer to a major version that matches the specified version and a minor version that is equal to or greater than the specified version. The list may include string bindings exported for other versions of the interface that are upwardly compatible, rather than for this particular version of the interface. Privilege Required You need read permission to the CDS object entry (the target name service entry). NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES The following command operates from the system prompt to show the name service entry /.:/LandS/anthro/calendar_mgr_node_3. $ rpccp show entry /.:/LandS/anthro/Cal_host_3 The following commands run the control program and show the name service entry /.:/LandS/anthro/Calendar_group: $ rpccp rpccp> show entry \ > /.:/LandS/anthro/Calendar_group RELATED INFORMATION Commands: add entry remove entry 5 show_group NAME show group - Shows the members of a group SYNOPSIS rpccp show group group-entry-name [-m member] [-r [integer]] [-s syntax] [-u] OPTIONS -m Declares the name of a single group member. -r Indicates that the show group operation recurses. If any members of a group are also groups, their entries are shown. By default, the -r option causes the show group operation to recurse until all nested groups are expanded; for example, -r shows the members of the specified group and all nested groups. You can limit recursion to one or more levels by specifying a decimal integer as part of the -r option. For example, -r 1 shows the members of the specified group and, for members that are groups, the command also shows their members; then recursion stops. Without the -r option, only the members of the specified group are shown. -s Indicates the name syntax of the entry name (optional). The only value for this option is the dce name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the -s option is unnecessary. -u Updates the local CDS cache copy of name service data (optional). Name service data is cached locally on each machine in a cell. If an rpccp inquiry can be satisfied by data in the local CDS cache, this cached data is returned. Locally cached copies of name service data might not include a recent CDS update, however. If the required data is not available in the local CDS cache, rpccp goes to a CDS server(s) to retrieve the required data. rpccp then updates the local CDS cache. Using the -u option bypasses the local cache, allowing rpccp to go directly to a CDS server for the inquiry. rpccp then updates the local CDS cache. ARGUMENTS group-entry-name Indicates the name of the target group. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. DESCRIPTION The show group command shows the members of a group in the name service database. The entry name of the group is required. Unless it is limited to a specific member (by the -m option), the show group command shows all members. The command shows only the members in the specified group; the -r option enables you to show members of nested groups. Privilege Required You need read permission to the CDS object entry (the target group entry). If you use the -r option, you also need read permission to any nested groups. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES The following example shows all the members of the group /.:/LandS/anthro/Calendar_group, in the order in which they were added to the group: $ rpccp rpccp> show group /.:/LandS/anthro/Calendar_group The following command operates from the system prompt to show a specific member of the group /.:/LandS/dept/Calendar_group: $ rpccp show group \ > -m /.:/LandS/anthro/Cal_host_2 \ > /.:/LandS/anthro/Calendar_group RELATED INFORMATION Commands: add member remove group remove member 5 show_mapping NAME show mapping - Shows the elements of the either the local or a remote endpoint map SYNOPSIS rpccp show mapping [host-address] [-i if-id [-v versions]] [-o object-uuid [ -o object-uuid...]] OPTIONS -i Defines an interface identifier to be shown (optional). Only one interface can be shown in a single operation. If specified, only elements containing this interface identifier are shown. The -i option can be qualified by the -v option. The value has the following form: interface-uuid,major-version.minor-version The UUID is a hexadecimal string and the version numbers are decimal strings, for example: -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 Leading zeros in version numbers are ignored. -v Indicates how a specified interface version is used (optional). If it is used without the -i option, the -v option is ignored. The possible combinations of versions for the -v option and their actions are described in the following table. ________________________________________________ Versions Action ________________________________________________ all The interface version is ignored. exact Both the major and minor versions must match the specified versions. compatible The major version must match the specified version, and the minor version must be greater than or equal to the specified version. major_only The major version must match the specified version; the minor ver- sion is ignored. upto The major version must be less than or equal to that specified. If the major versions are equal, the minor version must be less than or equal to that specified. ________________________________________________ If the -v option is absent, the command shows compatible version numbers. -o Defines an object to be shown (optional). Each show mapping command accepts up to 32 -o options. The UUID is a hexadecimal string, for example: -o 3c6b8f60-5945-11c9-a236-08002b102989 ARGUMENTS host-address The host-address argument is a string binding that indicates where to find the target endpoint map. When accessing the local endpoint map, you can specify which protocol sequence to use (optional); for example, ncadg_ip_udp: When accessing a remote endpoint map, you must specify both a protocol sequence and a network address for the remote system (required); for example, ncadg_ip_udp:16.20.16.44 An endpoint is unnecessary in local or remote host addresses, and the remove mapping command ignores any endpoint specified as part of a host address. DESCRIPTION The show mapping command shows elements of an endpoint map. Each element corresponds to an object UUID, interface identifier, annotation, and binding information. The binding information contains an RPC protocol sequence, a network address, and an endpoint within square brackets (rpc- protseq:network-addr[endpoint]). The endpoint map can be either the local endpoint map or the endpoint map of a specified remote host. If entered without a remote host address, the command accesses the local endpoint map. For the local endpoint map, a show mapping command without any options displays all the map elements. For a remote endpoint map, map elements are accessible only for protocol sequences that are supported on both your system and the remote system. The options list a selected subset of map elements. The - i option selects a specific interface, and the -v option qualifies the -i option. The -o object selects a specific object. You can use from 0 to 32 -o options per command. The options work together to specify the subset of elements for the target protocol sequence(s). NOTES Note that to ensure that you can remotely display all map elements from every remote endpoint map, run the RPC control program on a system that supports all of the protocol sequences available in your network environment. This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES The following commands start the control program and show the map elements in the local endpoint map that contain the specified interface identifier: $ rpccp rpccp> show mapping -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 The following rpccp show mapping command operates from the system prompt. The command accesses the endpoint map of the remote host specified by the host address (ncadg_ip_udp:16.20.16.44) and displays the one map element that contains both the specified interface identifier and the specified object UUID: $ rpccp show mapping \ > -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \ > -o 30dbeea0-fb6c-11c9-8eea-08002b0f4528 \ > ncadg_ip_udp:16.20.16.44 RELATED INFORMATION Commands: remove mapping show server 5 show_profile NAME show profile - Shows the elements of a profile SYNOPSIS rpccp show profile profile-entry-name {-d | -a annotation | -i if-id [-v versions] -m member} [-r [integer]] [-s syntax] [-u] OPTIONS -d Selects the default profile element. With the -d option, the -a, -i, and -m options are ignored. Note that the -a option works with the -d option, but do not use them together. -a Declares a single annotation field (optional). The -a option selects only elements containing the specified annotation. The option is case sensitive. The -a option works alone or in combination with the -i or -m options or both; only elements containing all the specified values are displayed. Note that the shell supports quotation marks around the annotation field of profile elements, allowing you to include internal spaces in an annotation; the control program does not. To specify or refer to annotations from within the control program, limit each annotation to an unbroken alphanumeric string; for example, CalendarGroup. To refer to annotations from the system prompt, do not incorporate quotation marks into any annotation. -i Selects a specified interface identifier (optional). Only elements containing that interface identifier are shown. The interface identifier value has the following form: interface-uuid,major-version.minor-version The UUID is a hexadecimal string and the version numbers are decimal strings, for example: -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 Leading zeros in version numbers are ignored. The -i option works alone or in combination with the -a or -m options or both; only elements containing all the specified values are displayed. When the -d option is specified, the -i option is ignored. -m Declares a single member name (optional). Only elements containing that member name are shown. The -m option works alone or in combination with the -a or -i options or both; only elements containing all the specified values are displayed. When the -d option is specified, the -m option is ignored. -r Indicates that the show profile operation recurses. If the member of any element of a profile is also a profile, its elements are shown. By default, the -r option causes the show profile operation to recurse until all nested profiles are expanded; for example, -r shows the elements of the specified profile and of all nested profiles. You can limit recursion to one or more levels by specifying a decimal integer as part of the -r option. For example, -r 1 shows the elements of the specified profile and, for element members that are profiles, the command also shows their elements; then recursion stops. Without the -r option, only the profile elements in the specified entry are shown. -s Indicates the name syntax of the entry name (optional). The only value for this option is the dce name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the -s option is unnecessary. -u Updates the local CDS cache copy of name service data (optional). Name service data is cached locally on each machine in a cell. If an rpccp inquiry can be satisfied by data in the local CDS cache, this cached data is returned. Locally cached copies of name service data might not include a recent CDS update, however. If the required data is not available in the local CDS cache, rpccp goes to a CDS server(s) to retrieve the required data. rpccp then updates the local CDS cache. Using the -u option bypasses the local cache, allowing rpccp to go directly to a CDS server for the inquiry. rpccp then updates the local CDS cache. -v Indicates how a specified interface version is used (optional). If it is used without the -i option, the -v option is ignored. The possible combinations of versions for the -v option and their actions are described in the following table. ________________________________________________ Versions Action ________________________________________________ all The interface version is ignored. exact Both the major and minor versions must match the specified versions. compatible The major version must match the specified version, and the minor version must be greater than or equal to the specified version. major_only The major version must match the specified version; the minor ver- sion is ignored. upto The major version must be less than or equal to that specified. If the major versions are equal, the minor version must be less than or equal to that specified. ________________________________________________ If the -v option is absent, the command shows compatible version numbers. ARGUMENTS profile-entry-name Indicates the name of the target profile. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. DESCRIPTION The show profile command shows the elements of a profile in the name service database. The entry name of the profile is required. By default, all elements in the profile are shown. You can select a subset of the elements by specifying the -a, -i, or -m options. The -r option enables you to show nested profiles. Privilege Required You need read permission to the CDS object entry (the target profile entry). If you use the -r option, you also need read permission to any nested profiles. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES The following command operates from the system prompt to show the cell profile /.:/cell-profile in the local cell: $ rpccp show profile /.:/cell-profile The initial DCL command sets up a logical name MOLLY_O_PROFILE, which represents the user profile /.:/LandS/anthro/molly_o_profile. The control program commands start the control program and show the user profile associated with the MOLLY_O_PROFILE logical name, as follows: $ define MOLLY_O_PROFILE "/.:/LandS/anthro/molly_o_profile" $ rpccp rpccp> show profile MOLLY_O_PROFILE RELATED INFORMATION Commands: add element remove element remove profile 5 show_server NAME show server - Shows the binding information, interface identifiers, and object UUIDs in a server entry SYNOPSIS rpccp show server server-entry-name [-i [if-id]] [-o [object-uuid]] [-s syntax] [-u] OPTIONS -i Shows interface identifiers from binding information found in the entry (optional). Without the -i option, the command displays all interface identifiers. To display a specific interface, supply its identifier as the value. The value has the following form: interface-uuid,major-version.minor-version The UUID is a hexadecimal string and the version numbers are decimal strings, for example: -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 Leading zeros in version numbers are ignored. -o Shows object UUIDs found in the entry (optional). Without the -o option, the command displays all object UUIDs. To display a specific object UUID, supply its string representation as the value, for example: -o 3c6b8f60-5945-11c9-a236-08002b102989 -s Indicates the name syntax of the entry name (optional). The only value for this option is the dce name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the -s option is unnecessary. -u Updates the local CDS cache copy of name service data (optional). Name service data is cached locally on each machine in a cell. If an rpccp inquiry can be satisfied by data in the local CDS cache, this cached data is returned. Locally cached copies of name service data might not include a recent CDS update, however. If the required data is not available in the local CDS cache, rpccp goes to a CDS server(s) to retrieve the required data. rpccp then updates the local CDS cache. Using the -u option bypasses the local cache, allowing rpccp to go directly to a CDS server for the inquiry. rpccp then updates the local CDS cache. ARGUMENTS server-entry-name Indicates the name of the target server. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. DESCRIPTION The show server command shows the RPC binding information, interface identifiers, and object UUIDs in a server entry. The entry name of the server entry is required. This operation shows all of the potential bindings for an interface. By default, this command displays bindings for the specified version of the interface and for upwardly compatible versions of the interface. The -v option controls which versions are targeted by this command. Privilege Required You need read permission to the CDS object entry (the target server entry). NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES The following commands start the control program and show the server entry /.:/LandS/anthro/Cal_host_2 in the local cell: $ rpccp rpccp> show server /.:/LandS/anthro/Cal_host_2 The following command operates from the system prompt to display a specific object and interface from the server entry /.:/LandS/anthro/Cal_host_2 in the local cell: $ rpccp show server \ > /.:/LandS/anthro/Cal_host_2 \ > -o 16977538-e257-11c9-8dc0-08002b0f4528 \ > -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 RELATED INFORMATION Commands: export import unexport 5 unexport NAME unexport - Removes binding information, interface identifiers, and object UUIDs from a server entry SYNOPSIS rpccp unexport entry-name {[-i if-id [-v versions]] | [-o object-uuid]} [-s syntax] OPTIONS -i Defines an interface identifier to be unexported (optional). Only one interface can be unexported in a single operation. If specified, binding information for this interface is removed from the entry. The -i option can be qualified by the -v option. The value has the following form: interface-uuid,major-version.minor-version The UUID is a hexadecimal string and the version numbers are decimal strings, for example: -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 Leading zeros in version numbers are ignored. -v Indicates how a specified interface version is used (optional). If it is used without the -i option, the -v option is ignored. The possible combinations of versions for the -v option and their actions are described in the following table. Versions Action ________________________________________________ all The interface version is ignored. exact Both the major and minor versions must match the specified versions. compatible The major version must match the specified version, and the minor version must be greater than or equal to the specified version. major_only The major version must match the specified version; the minor ver- sion is ignored. upto The major version must be less than or equal to that specified. If the major versions are equal, the minor version must be less than or equal to that specified. ________________________________________________ If the -v option is absent, the command shows compatible version numbers. -o Defines an object to be unexported (optional). Each unexport command accepts up to 32 -o options. The UUID is a hexadecimal string, for example: -o 3c6b8f60-5945-11c9-a236-08002b102989 -s Indicates the name syntax of the entry name (optional). The only value for this option is the dce name syntax, which is the default name syntax. Until an alternative name syntax becomes available, specifying the -s option is unnecessary. ARGUMENTS entry-name Indicates the name of the target name service entry. Usually, the target is a server entry. However, objects also can be exported (without an interface identifier or binding information) to a group or a profile. For an entry in the local cell, you can omit the cell name and specify only the cell-relative name. DESCRIPTION The unexport command removes binding information and an interface identifier, object UUIDs, or both from a server entry, or it removes object UUIDs from a group's entry. The command requires the entry name and either the interface identifier or one or more object UUIDs. By default, the unexport operation removes compatible interface versions. Privilege Required You need both read permission and write permission to the CDS object entry (the target name service entry). NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES The initial DCL command sets up a logical name Calendar_1_1, which represents the interface identifier of an RPC interface. The control program commands start the control program and remove (unexport) the Calendar Version 1.1 interface from the server entry /.:/LandS/anthro/Cal_host_2 in the local cell, as follows: $ define Calendar_1_1 "ec1eeb60-5943-11c9-a309-08002b102989,1.1" $ rpccp rpccp> unexport \ > -i Calendar_1_1 \ > /.:/LandS/anthro/Cal_host_2 rpccp> RELATED INFORMATION Commands: export import show server 4 Environmental_Influences_on_Command_Syntax Environmental Influences on Command Syntax There are variations in the action of the control program, depending on whether commands are entered from the system prompt or from within the control program. For example, entering the annotation field of profile elements from the system prompt allows you to include internal spaces in an annotation. Function At System Prompt Inside Control Program _______________________________________________________________ Strings within quotation Supported Not required marks Wildcard substitution Supported Unsupported _______________________________________________________________ Some UNIX systems require that you place an escape symbol (\) before string binding delimiters such as brackets ([ ]) or that you place the delimiters within quotation marks (' ' or " ") at the system prompt. 4 Scope_of_the_RPC_Control_Program_Commands The following table describes the scope of the RPC control program commands. Scope Command _____________________________ All entries add entry remove entry show entry Server entry export import show server unexport Group add member remove group remove member show group Profile add element remove element remove profile show profile Endpoint map add mapping remove mapping show mapping _____________________________ 4 Logical_Names The control program supports logical names. Using logical names facilitates interactive use of the control program. To distinguish logical names, rpccp* reference pages follow the convention of using all uppercase letters for examples of logical names. Note that OpenVMS logical names are NOT case sensitive. User-defined logical names You can set a logical name to represent values to rpccp. Using a logical name is helpful for specifying a long string such as the following: + A string representation of binding information (binding string) + A string representation of an object or interface UUID (string UUID) + An interface identifier (the interface UUID and version numbers) + The name of a name service entry For example, in the following example, the logical name JANE_CAL represents an object UUID; the target name service entry, /.:/LandS/anthro/Cal_host_2, is in the local cell: $ DEFINE JANE_CAL 47f40d10-e2e0-11c9-bb29-08002b0f4528 $ rpccp rpccp> export -o JANE_CAL /.:/LandS/anthro/Cal_host_2 DCE RPC logical names The dce name syntax is the only syntax currently supported by the DCE Cell Directory Service (CDS). However, the Name Service Interface (NSI) is independent of any specific name service and, in the future, may support name services that use other name syntaxes. When alternative name syntaxes are supported, you can override the standard default with a process-specific default by setting the RPC_DEFAULT_ENTRY_SYNTAX logical name. When this variable is set for a process, the control program uses it to find out the default syntax for the process. You can override this default in any NSI command of the control program by using the -s option to specify an alternative entry syntax. Setting RPC_DEFAULT_ENTRY_SYNTAX requires specifying the integer 3 to indicate the dce syntax. To set RPC_DEFAULT_ENTRY_SYNTAX, use the name=value command to define a logical name. The following command specifies dce as the default name syntax in a login command file: # .login command file # setting dce as default name syntax, RPC_DEFAULT_ENTRY_SYNTAX=3 RPC_DEFAULT_ENTRY For the import command, you can use this environment variable to indicate the entry where the search operation starts. Usually, the starting entry is a profile. 4 Name_Service_Interface The remainder of this description contains information to help you use commands that call the name service interface to access name service entries (NSI commands). The DCE RPC name service interface (NSI) is independent of any particular name service. CDS, however, is the only name service available for DCE RPC Version 1.0 applications. For more details on the name service interface, see the OSF DCE Application Development Guide-Core Components. For a description of the DCE Cell Directory Service, see the OSF DCE Administration Guide-Core Components. 5 Name_Service_Entries To store information about RPC servers, interfaces, and objects, the NSI defines the following name service entries: server entry Stores binding information, interface identifiers, and object UUIDs for an RPC server. group Corresponds to one or more RPC servers that offer a common RPC interface, type of RPC object, or both. profile Defines search paths for looking in a name service database for a server that offers a particular RPC interface and object. Note that when the NSI is used with the Cell Directory Service, the name service entries are CDS object entries. 5 Structure_of_Entry_Names Each entry in a name service database is identified by a unique global name made up of a cell name and a cell-relative name. A cell is a group of users, systems, and resources that share common DCE services. A cell configuration includes at least one cell directory server, one security server, and one time server.A cell's size can range from one system to thousands of systems. For information on cells, see the CDS portion of this book. The following is an example of a global name: /.../C=US/O=uw/OU=MadCity/LandS/anthro/Stats_host_2 The parts of a global name are as follows: Cell name (using X.500 name syntax) For example: /.../C=US/O=uw/OU=MadCity The symbol /... begins a cell name. The letters before the equal signs (=) are abbreviations for country (C), organization (O), and organization unit (OU). For entries in the local cell, the cell name can be represented by a /.: prefix, in place of the actual cell name; for example, /.:/LandS/anthro/Stats_host_2 For NSI operations on entries in the local cell you can omit the cell name. Cell-relative name Each name service entry requires a cell-relative name, which contains a directory pathname and a leaf name. directory pathname Follows the cell name and indicates the hierarchical relationship of the entry to the cell root. The directory pathname is the middle portion of the global name. The cell name is to the left of the directory pathname, and the leaf name is to the right, as follows: cell-name + directory-pathname + leaf-name The directory pathname contains the names of any subdirectories in the path; each subdirectory name begins with a slash (/), as follows: /sub-dir-a-name/sub-dir-b-name/sub-dir-c-name Directory paths are created by name service administrators. If an appropriate directory path does not exist, ask your name service administrator to extend an existing path or create a new path. In a directory path, the name of a subdirectory should reflect its relationship to its parent directory (the directory that contains the subdirectory). leaf name Identifies the specific entry. The leaf name is the right-hand part of global name beginning with the rightmost slash. In the following example, /.../C=US/O=uw/OU=MadCity is the cell name, /LandS/anthro is the directory pathname, and /Cal_host_4 is the leaf name. /.../C=US/O=uw/OU=MadCity/LandS/anthro/Cal_host_4, If a name service entry is located at the cell root, the leaf name directly follows the cell name; for example, /.:/cell-profile. Note that when the NSI is used with CDS, the cell-relative name is a CDS name. 5 Guidelines_for_Constructing_Names_of_Name_Service_Entries A global name includes both a cell name and a cell-relative name composed of a directory pathname and a leaf name. The cell name is assigned to a cell root at its creation. When you specify only a cell-relative name to an NSI command, the NSI automatically expands the name into a global name by inserting the local cell name. When returning the name of a name service entry, a group member, or member in a profile element, NSI operations return global names. The directory pathname and leaf name uniquely identify a name service entry. The leaf name should somehow describe the entry; for example, by identifying its owner or its contents.The remainder of this section contains guidelines for choosing leaf names. Note that directory pathnames and leaf names are case sensitive. Naming a Server Entry For a server entry that advertises an RPC interface or service offered by a server, the leaf name must distinguish the entry from the equivalent entries of other servers. When a single server instance runs on a host, you can ensure a unique name by combining the name of the service, interface (from the interface definition), or the system name for the server's host system. For example, consider two servers, one offering a calendar service on host JULES and one, on host VERNE. The server on JULES uses the following leaf name: calendar_JULES The server on VERNE uses the following leaf name: calendar_VERNE For servers that perform tasks on or for a specific system, an alternative approach is to create server entries in a system- specific host directory within the name service database. Each host directory takes the name of the host to which it corresponds. Because the directory name identifies the system,the leaf name of the server entry name need not include the host name, for example: /.:/LandS/host_1/Process_control To construct names for the server entries used by distinctive server instances on a single host, you can construct unique server entry names by combining the following information: the name of the server's service, interface, or object; the system name of the server's host system, and a reusable instance identifier, such as an integer. For example,the following leaf names distinguish two instances of a calendar service on the JULES system: calendar_JULES_01 calendar_JULES_02 Avoid automatically generating entry names for the server entries of server instances, for example, by using unique data such as a time stamp (calendar_verne_15OCT91_21:25:32) or a process identifier (calendar_jules_208004D6). When a server incorporates such unique data into its server entry names, each server instance creates a separate server entry, causing many server entries. When a server instance stops running, it leaves an obsolete server entry that is not reused. The creation of a new entry whenever a server instance starts may impair performance. A server can use multiple server entries to advertise different combinations of interfaces and objects. For example, a server can create a separate server entry for a specific object (and the associated interfaces). The name of such a server entry should correspond to a well-known name for the object. For example,consider a server that offers a horticulture bulletin board known to users as horticulture_bb. The server exports th horticulture_bb object, binding informa- tion, and the associated bulletin-board interface to a server entry whose leaf name identifies the object, as follows: horticulture_bb Note that an RPC server that uses RPC authentication can choose identical names for its principal name and its server entry. Use of identical names permits a client that calls the rpc_binding_set_auth_info routine to automatically determine a server's principal name (the client will assume the principal name to be the same as the server's entry name). If a server uses different principal and server entry names, users must explicitly supply the principal name. For an explanation of principal names, see the DCE Security Service part of the DCE Application Development Guide. Naming a Group The leaf name of a group should indicate the interface, service,or object that determines membership in the group. For example, for a group whose members are selected because they advertise an interface named Statistics, the following is an effective leaf name: Statistics For a group whose members advertise laser-printer print queues as objects, the following is an effective leaf name: laser-printer Naming a Profile The leaf name of a profile should indicate the profile users; for example, for a profile that serves the members of an accounting department, the following is an effective leaf name: accounting_profile 5 Permissions_Required To use the NSI commands to access entries in a CDS database, you need access control list (ACL) permissions. Depending on the NSI operation, you need ACL permissions to the parent directory or the CDS object entry (the name service entry) or both. The ACL permissions are as follows: + To create an entry, you need insert permission to the parent directory. + To read an entry, you need read permission to the CDS object entry. + To write to an entry, you need write permission to the CDS object entry. + To delete an entry, you need delete permission either to the CDS object entry or to the parent directory. Note that write permission does not imply read permission. ACL permissions for the NSI commands of the control program are described in the reference pages. 4 EXAMPLES The following command starts the RPC control program: $ rpccp rpccp> The following command at the system prompt removes the entry /.:/LandS/anthro/Cal_host_2: $ rpccp remove entry \ > /.:/LandS/anthro/Cal_host_2 3 rpcd NAME rpcd - DCE Remote Procedure Call Daemon DESCRIPTION The DCE Remote Procedure Call Daemon (RPCD) has been replaced by the DCE Daemon (DCED) as of OSF DCE Version 1.1. RELATED_INFORMATION See "DCE dce_tools_intro dced" for a descripton of the new DCE daemon. 2 DCE_CDS DCE Cell Directory Services (CDS) provide a location-independent method of identifying resources within a cell. A cell is the smallest group of DCE systems that share a common naming and security domain. 3 Administration_Intro NAME cds_intro - Introduction to the CDS commands DESCRIPTION The DCE Cell Directory Service provides the following management commands: o The cdsbrowser command starts the CDS Browser utility. This utility is based on the OSF/Motif graphical user interface. The Browser can display an overall directory structure as well as show the contents of directories. o The nsedit command starts the CDS namespace editor utility. This utility is based on the OSF/Motif graphical user interface. The editor can not only display directory structure and contents, but also allows modification of entries shown. o The cdscp command starts the CDS control program. Use this command line interface to manage the CDS components and the contents of your namespace. The following commands are typically started automatically by scripts that execute as part of normal system start-up procedures. See the reference pages for these commands before you try to use them. o The cdsadv command starts the advertisement and solicitation daemon on the local system. Use this command only when troubleshooting because the CDS advertiser process is normally started automatically by scripts that execute as part of normal system start-up procedures. o The cdsclerk command restarts the CDS clerk. Use this command only when troubleshooting because the CDS clerk process is normally started automatically by scripts that execute as part of normal system start-up procedures. o The cdsd command restarts the CDS server. Use this command only when troubleshooting because cdsd is normally started automatically by scripts that execute as part of normal system start-up procedures. o The gdad command starts the GDA (Global Directory Agent) daemon. The GDA enables intercell communication, serving as a connection to other cells through the global naming environment. The GDA is typically started automatically by scripts that execute as part of normal system start-up procedures. RELATED INFORMATION Book: DCE Administration Guide Commands: cdsadv cdsbrowser cdsclerk cdscp cdsd gdad dced nsedit 3 cdsadv NAME cdsadv - Starts the advertisement and solicitation daemon SYNOPSIS cdsadv [-c] [-D] [-s] [-w route] ARGUMENTS -c Specifies cache size in kilobytes. -D For debugging use only. -s Causes the server not to send or receive advertisements. This argument can be used for diagnostic work involving multiple servers on the same local area network to limit access to those servers identified with the define cached server command. -w route Routes serviceability messages. DESCRIPTION The cdsadv command starts the advertisement and solicitation daemon on the local system. Privilege Required You must log in as DCE$SERVER. NOTES This command is ordinarily executed by the CDS startup script on the system where the CDS server is running. You should use this command interactively only to do diagnostic work on the host system. EXAMPLE To restart a clerk, enter the following command: $ @sys$manager:dce$setup start To debug a clerk, follow these steps: 1. Log in to the clerk system as DCE$SERVER. 2. Log in to DCE as the machine principal of the local host. Enter the principal name in the format hosts/hostname/self as shown in the following example command for a host named orion whose password is smith: $ dce_login hosts/orion/self smith 3. Enter the following command to see if the dced process is already running: $ show system If the dced process appears on the list of active processes, proceed to step 4. If the dced process does not appear on the list of active processes, enter the following command to start the process: $ run sys$system:dce$dced 4. Enter the following command to start the cdsadv process: $ run sys$system:dce$cdsadver RELATED INFORMATION Books: OSF DCE Administration Guide 3 cdscp NAME cdscp - Starts the CDS control program SYNOPSIS cdscp [cdscp-command] ARGUMENTS See Command_Summary RELATED INFORMATION Books: OSF DCE Administration Guide 4 Command_Summary cdscp-command Optionally, specifies one of the following control commands: add directory Adds a value to a modifiable, set-valued attribute (including application-defined attributes) of a directory add object Adds a value to a modifiable, set-valued attribute (including application-defined attributes) of an object entry clear cached server Removes knowledge of a server that you had specifically defined from the local clerk's cache clear clearinghouse Removes knowledge of the specified clearinghouse from the server's memory create child Creates a child pointer at the master replica of the parent directory create clearinghouse Creates a clearinghouse on the local server system or makes an existing clearinghouse available create directory Creates a directory create link Creates a soft link and optionally specifies an expiration time and an extension time create object Creates a new object entry create replica Creates a replica of an existing directory in the specified clearinghouse define cached server Creates knowledge of a server in the local clerk's cache delete child Deletes a child pointer from the namespace delete clearinghouse Deletes the specified clearinghouse from the local server system delete directory Deletes a directory delete link Deletes a soft link delete object Deletes an object entry delete replica Deletes a read-only replica of a directory from a clearinghouse disable clerk Stops the clerk on the local system disable server Stops the server on the local system dump clerk cache Displays the contents of the clerk cache help Displays a list of the CDS control program commands list child Displays a list of all the child pointers whose names match the specified child name list clearinghouse Displays a list of all the clearinghouses whose names match the specified clearinghouse name list directory Displays a list of all the directories whose names match the specified directory name list link Displays a list of all the soft links whose names match the specified link name list object Displays a list of all the object entries (including clearinghouse object entries) whose names match the specified object entry name remove directory Removes a value from a set-valued or single-valued attribute (including application-defined attributes) of a directory remove link Removes a soft link's timeout value attribute remove object Removes a value from a set-valued or single-valued attribute (including application-defined attributes) of an object entry set cdscp confidence Sets the confidence level of clerk calls issued as a result of CDS control program commands set cdscp preferred clearinghouse Specifies a preferred clearinghouse to use for satisfying read requests that result from CDS control program commands set directory Changes the value of a modifiable, single-valued attribute of a directory set directory to new epoch Reconstructs a directory's replica set, allowing you to designate a new master replica or to exclude a replica set directory to skulk Starts the skulk of a directory immediately set link Changes the value of a modifiable, single-valued attribute of a soft link set object Changes the value of a modifiable, single-valued attribute of an object entry show cached clearinghouse Displays current information about the specified cached clearinghouse show cached server Displays address information of a server in the local clerk's cache show cdscp confidence Displays the current confidence level of clerk calls resulting from CDS control program commands show cdscp preferred clearinghouse Displays the preferred clearinghouse for satisfying read requests that result from CDS control program commands show cell Displays the information you need to create a cell entry in either DNS or GDS show child Displays attribute information about the specified child pointer show clearinghouse Displays attribute information about the specified clearinghouse show clerk Displays attribute information about the CDS clerk on the local system show directory Displays attribute information about the specified directory show link Displays attribute information about the specified soft link show object Displays attribute information about the specified object entry show replica Displays attribute information about the specified replica show server Displays attribute information about the server running on the local system NOTES With the exception of the following subcommands, this command is replaced at Revision 1.1 by the dcecp command. This command may be fully replaced by the dcecp command in a future release of DCE, and may no longer be supported at that time. + disable clerk + disable server + help + set cdscp confidence + set directory to new epoch + show cdscp confidence + show cell + show clerk + show server 4 DESCRIPTION The Cell Directory Service (CDS) control program is a command line interface for managing the components of the Cell Directory Service and the contents of the namespace. You can use the control program commands from within the control program or from the system prompt. To use the control program commands from inside the control program, start the control program by using the cdscp command alone, without any argument. This enters the control program, which displays the control program prompt (cdscp>): $ cdscp cdscp> At this prompt, you can enter any control program command; for example: cdscp> show server Use the command do filename from inside the control program to read a file of commands. To leave the control program and return to the system prompt, use the quit command. To use the control program commands from the system prompt, enter the cdscp command with an internal command of the CDS control program as the first argument. The control program executes the command immediately, without displaying the control program prompt.For example, you can enter the show server command as follows: $ cdscp show server 5 Elements_of_a_CDS_Command All CDS control program commands must include a verb, an entity name, and all required arguments. Depending on the command, you can also specify optional arguments and attributes. A space must separate more than one attribute or argument. A space must precede and follow an equal sign (=). 6 Verbs The following is a list of the definitions of verbs used in control program commands: add Adds a value to a modifiable, set-valued attribute clear Removes knowledge of a cached clearinghouse or cached server from memory create Creates an entity define Creates knowledge of a locally cached server delete Deletes an entity disable Stops operation of a clerk or server dump Displays the contents of a clerk cache list Displays a list of specified entity names remove Removes a value from a set-valued or single-valued attribute set Changes the value of a modifiable, single-valued attribute show Displays attribute information 6 Entity_Names Any individually manageable piece of CDS is called an entity. A set of commands exists for each entity. The following is a list of the entities and a description of what each entity represents: Cached Clearinghouse A cached clearinghouse is a clearinghouse that a clerk has discovered and cached. A clerk can learn about clearinghouses as a result of configuration information, advertisements received on a LAN, or during the process of finding a name. Cached Server A cached server is a server that a clerk has cached as a result of manual configuration through the control program. Child A child pointer connects a parent and child directory in a hierarchical namespace. The child pointer is stored in the parent directory and has the same name as the child directory. Clearinghouse A clearinghouse is a database containing a collection of directory replicas at a particular server. Clerk The clerk is the interface between client applications and servers. Directory A directory contains child,object and link entries that are logically stored under one name (the directory name). Link A soft link is a pointer providing an alternate name for an object entry, directory, or other soft link. Object An object entry represents a resource (for example, an application) that is named in the namespace. Replica A replica is a copy of a directory. Each copy, including the original or master, is referred to as a replica. Server A server handles lookup requests from clerks and maintains the contents of the clearinghouse or clearinghouses at its node. 6 Attributes Every CDS entity has attributes, which are pieces or sets of data associated with that entity. Attributes can reflect or affect the operational behavior of an entity, record the number of times a particular event or problem occurred since the entity was last enabled, and uniquely distinguish an entity from any other entity. Some attributes have a single value; others contain a set of values. CDS attributes are identified by ISO object identifiers (OIDs). Every CDS attribute name maps to an OID and a corresponding data type. Usually, client applications define the name of an attribute and its data type. Application programmers should never need to modify (except for the purpose of foreign language trans- lation) the existing CDS labels associated with the unique OIDs in the cds_attributes file. However, programmers can obtain new OIDs from the appropriate allocation authority, create new attributes for their own object entries, and then append them to the existing list. The OID and data type of each attribute are stored in the file DCE$COMMON:[ETC]CDS_ATTRIBUTES.DAT. Descriptions of the CDS data types that applications can use are in the cdsclerk.h file. All entities have show commands that you can use to display the names and values of specific attributes or all attributes. When you display an attribute that has more than one value, the show command lists each value for the attribute separately. When there are multiple values for an attribute, the command first lists the attribute name on a line ending with a colon, then the parts of the value. For more information about CDS attributes, see the DCE Directory Service module in the DCE Administration Guide. 5 Editing_the_Commands You can abbreviate commands, continue a command beyond one line, or redirect output to a file within the control program. To abbreviate any command name, type only the first four characters. You can abbreviate a command name to fewer than four characters as long as the abbreviated name remains unique among all command names in the control program. For example, the following commands are equivalent: cdscp> show directory /.:/sales cdscp> sh dir /.:/sales To continue a long command line onto the next line, type a space and then a \ (backslash) at the end of the first line, for example: cdscp> set link /.:/sales CDS_LinkTimeout \ > (1991-12-31-12:00:00 090-00:00:00) To add a comment, use the # (number sign). Everything following the # character on a line is ignored. 5 Using_Wildcard_Characters When entering a name in show and list commands, you can use wildcard characters in the rightmost simple name (the name to the right of the last slash (/) in the full pathname). The asterisk (*) matches 0 or more characters in a simple name. The question mark (?) matches exactly one character in a simple name. When you use an asterisk or a question mark as a normal character in the rightmost simple name of a show or list command, escape it with a backslash (\* or \?). Otherwise, the character is interpreted as a wildcard. You cannot use wildcard characters in show clerk and show server commands. 5 Permissions_Required CDS supports the following DCE permissions: read (r), write (w), insert (i), delete (d), test (t), control (c), and administer (a). Each permission has a slightly different meaning, depending on the kind of CDS name with which it is associated. In general, the permissions are defined as follows: Read Allows a principal to look up a name and view the attribute values associated with it. Write Permission allows a principal to change the modifiable attributes associated with a name, except the name's access control list (ACL) entries. Insert Permission (for use with directory entries only) allows a principal to create new names in a directory. Delete Permission allows a principal to delete a name from the namespace. Test Permission allows a principal to test whether an attribute of a name has a particular value without being able to actually see any of the values (that is, without having read permission to the name). Test permission provides application programs a more efficient way to verify a CDS attribute value. Rather than reading an entire set of values, an application can test for the presence of a particular value. Control Permission allows a principal to modify the ACL entries associated with a name. (Note that read permission is also necessary for modifying a CDS entry's ACLs;otherwise, acl_edit will not be able to bind to the entry.) Control permission is automatically granted to the creator of a CDS name. Administer Permission (for use with directory entries only) allows a principal to issue CDS control program commands that control the replication of directories. The creator of a name is automatically granted all permissions appropriate for the type of name created. For example, a principal creating an object entry is granted read, write, delete, test, and control permission to the object entry. A principal creating a directory is granted read, write, insert, delete, test, control, and administer permission to the directory. 4 EXAMPLES The following command starts the CDS control program: $ cdscp cdscp> The following command operates from the system prompt to display the attributes of the CDS clerk on the local system: $ cdscp show clerk 4 add_directory NAME add directory - Adds a value to a modifiable, set-valued attribute (including application-defined attributes) of a directory SYNOPSIS cdscp add directory directory-name attribute-name = attribute-value ARGUMENTS directory-name The full name of the directory. attribute-name The name of a particular attribute. Specify only one attribute at a time. See the cds_attributes file for the list of attributes that your application uses. attribute-value The value of a particular attribute. The value of an application-defined attribute is dependent on the type of attribute. See the cds_attributes file for the list of attributes and corresponding data types that your application uses. If you enter a byte data type, you must enter an even number of digits in length. You can only enter pairs of hexadecimal values for user-defined attributes. DESCRIPTION The add directory command adds a value to a modifiable, set-valued attribute (including application-defined attributes) of a directory. If the attribute does not exist, this command creates it. Usually, this task is performed through the client application. See the DCE Administration Guide for more information about attributes. Privilege Required You must have write permission to the directory. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE To add the value ontario to the attribute myname of a directory named /.:/sales, read the cds_attributes file to verify that the attribute shown in the following display exists: OID LABEL SYNTAX 1.3.22.1.3.91 myname char Enter the following command to assign the value ontario to the attribute myname: cdscp> add directory /.:/sales myname = ontario RELATED INFORMATION Commands: remove directory show directory Books: OSF DCE Administration Guide 4 add_object NAME add object - Adds a value to a modifiable, set-valued attribute (including application-defined attributes) of an object entry SYNOPSIS cdscp add object object-name attribute-name = attribute-value ARGUMENTS object-name The full name of the object entry. attribute-name The name of a particular attribute. Specify only one attribute at a time. See the cds_attributes file for the list of attributes and corresponding data types that your application uses. attribute-value The value of a particular attribute. The value of an application-defined attribute is dependent on the type of attribute. DESCRIPTION The add object command adds a value to a modifiable, set-valued attribute (including application-defined attributes) of an object entry. If the attribute does not exist, this command creates it. Usually, this task is performed through the client application. See the DCE Administration Guide for more information about attributes. Privilege Required You must have write permission to the object entry. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE To add the value ps to the attribute printcap of an object entry named /.:/subsys/deskprinter, read the cds_attributes file to verify that the attribute shown in the following display exists: OID LABEL SYNTAX 1.3.22.1.3.70 printcap char Enter the following command to assign the value ps to the attribute printcap: cdscp> add object /.:/subsys/deskprinter printcap = ps RELATED INFORMATION Commands: create object delete object list object remove object set object show object Books: OSF DCE Administration Guide 4 clear_cached_server NAME clear cached server - Removes knowledge of a server that you had specifically defined from the local clerk's cache SYNOPSIS cdscp clear cached server name ARGUMENTS name The simple name given to the cached server when it is created. DESCRIPTION The clear cached server command removes knowledge of a server from the local clerk's cache. You can only clear servers that you have specifically created with the define cached server command. Privilege Required You must have write permission to the clerk. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES The following command removes knowledge of the server nrl from the clerk cache: cdscp> clear cached server nrl RELATED INFORMATION Commands: define cached server dump clerk cache show cached server 4 clear_clearinghouse NAME clear clearinghouse - Removes knowledge of the specified clearinghouse from the server's memory SYNOPSIS cdscp clear clearinghouse clearinghouse-name ARGUMENTS clearinghouse-name The full name of the clearinghouse. DESCRIPTION The clear clearinghouse command removes knowledge of the specified clearinghouse from the server's memory. The clearinghouse files are not deleted. This ensures that the clearinghouse is not automatically enabled on server restarts. If you issue a list clearinghouse command, the clearinghouse will be listed. Before you can delete a cleared clearinghouse, you must use the create clearinghouse command to recreate it. After recreating the clearinghouse, you can use the delete clearinghouse command to remove it. This command is part of the process of relocating a clearinghouse. See the OSF DCE Administration Guide for more information. Privilege Required You must have write permission to the server on which the clearinghouse resides. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES The following command clears the clearinghouse /.:/Paris2_CH before moving it to another server: cdscp> clear clearinghouse /.:/Paris2_CH RELATED INFORMATION Books: OSF DCE Administration Guide Commands: create clearinghouse delete clearinghouse list clearinghouse set cdscp preferred clearinghouse show cdscp preferred clearinghouse show clearinghouse 4 create_child NAME create child - Creates a child pointer at the master replica of the parent directory SYNOPSIS cdscp create child child-name clearinghouse clearinghouse-name ARGUMENTS child-name The full name of the child pointer. clearinghouse-name The full name of a clearinghouse that contains a replica of the child directory. DESCRIPTION The create child command creates a child pointer at the master replica of the parent directory. When CDS looks up a name in the namespace, it uses child pointers to locate directory replicas. Use the set cdscp preferred clearinghouse command before issuing this command to ensure that the request is directed to the master replica. Privilege Required You must have insert permission to the parent directory. NOTES Use the create child command only to re-create a child pointer that is accidentally deleted. This command is designed only for troubleshooting. This command will fail if the associated directory does not exist. If the associated directory exists, this command will return successfully. This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command creates the child pointer in the parent directory /.:/subsys. It uses the replica located at the /.:/subsys/NY_CH clearinghouse to fill in its replica set. cdscp> create child /.:/subsys clearinghouse /.:/subsys/NY_CH RELATED INFORMATION Commands: delete child list child show child 4 create_clearinghouse NAME create clearinghouse - Creates a clearinghouse on the local server system or makes an existing clearinghouse available SYNOPSIS cdscp create clearinghouse clearinghouse-name ARGUMENTS clearinghouse-name The full name of the clearinghouse. DESCRIPTION The create clearinghouse command creates a clearinghouse on the local server system or makes an existing clearinghouse available. The server start-up command usually creates a new clearinghouse when you configure a new CDS server. Occasionally, you may need to create a second clearinghouse on a particular server; for example, if you are temporarily relocating a clearinghouse on a different server. See the OSF DCE Administration Guide for more information about relocating a clearinghouse. Clearinghouses should be named only in the root. When you enter the command, CDS creates a read-only replica of the root directory and stores it in the new clearinghouse as the initial replica. Because the process that creates the new clearinghouse initiates a skulk of the root directory, all replicas of the root should be reachable when you enter the command. Privilege Required You need write permission to the server on which you intend to create the clearinghouse and administer permission to the cell root directory. The server principal needs read, write, and administer permission to the cell root directory. NOTES This command is usually executed only by the network configuration procedure. To ensure that all replicas of the root are reachable, perform an immediate skulk of /.: prior to issuing this command. This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command creates a clearinghouse named /.:/Boston_CH on the local server system: cdscp> create clearinghouse /.:/Boston_CH RELATED INFORMATION Commands: clear clearinghouse delete clearinghouse list clearinghouse set cdscp preferred clearinghouse show cached clearinghouse show cdscp preferred clearinghouse show clearinghouse Books: OSF DCE Administration Guide 4 create_directory NAME create directory - Creates a directory SYNOPSIS cdscp create directory directory-name [clearinghouse clearinghouse-name] ARGUMENTS directory-name The full name of the directory clearinghouse-name The name of the clearinghouse in which you create the directory. DESCRIPTION The create directory command creates a directory with the name that you specify. If you do not specify a clearinghouse, CDS creates the master replica of the directory in the same clearinghouse as the new directory's parent directory. Privilege Required You must have the following permissions in order to create a directory: + read and insert permission to the parent directory; + write permission to the clearinghouse in which the master replica of the new directory is to be stored. In addition, the server principal must have read and insert permission to the parent directory. NOTES To ensure that all replicas are consistent, perform an immediate skulk of the parent directory after issuing this command. This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command creates a directory named /.:/sales. cdscp> create directory /.:/sales RELATED INFORMATION Commands: delete directory list directory set directory set directory to skulk show directory 4 create_link NAME create link - Creates a soft link and optionally specifies an expiration time and an extension time SYNOPSIS cdscp create link link-name CDS_LinkTarget = target-name [CDS_LinkTimeout = (expiration-time extension-time)] ARGUMENTS link-name The full name of the soft link. target-name The full name of the entry to which the soft link points. expiration-time A date and time after which CDS checks for existence of the soft link's target and either extends or deletes the soft link. The value is specified as yyyy-mm-dd-hh:mm:ss (year-month-day-hour:minute:second). You can abbreviate this value. extension-time A period of time by which to extend the soft link's expiration time (if the server has validated that the target still exists). The value is specified as ddd-hh:mm:ss (days-hour:minute:second). You can abbreviate this value. DESCRIPTION The create link command creates a soft link. If you specify the CDS_LinkTimeout attribute, you must specify an expiration time and an extension time. If you omit the CDS_LinkTimeout attribute, the soft link is permanent and must be explicitly deleted. Privilege Required You must have insert permission to the directory in which you intend to create the soft link. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command creates a permanent soft link named /.:/sales/tokyo/price-server that points to an object entry named /.:/sales/east/price-server. The expiration value indicates that CDS will check that the destination name /.:/sales/east/price-server still exists on June 25,1995, at 12:00 p.m. If the destination name still exists, the soft link remains in effect another 90 days. Thereafter, CDS will check that the destination name exists every 90 days. cdscp> create link /.:/sales/tokyo/price-server CDS_LinkTarget \ > = /.:/sales/east/price-server CDS_LinkTimeout = \ > (1995-06-25-12:00:00 = 90-00:00:00) RELATED INFORMATION Commands: delete link list link set link show link 4 create_object NAME create object - Creates an object entry SYNOPSIS cdscp create object object-name [CDS_Class = class-name CDS_ClassVersion = value] ARGUMENTS object-name The full name of the object entry. class-name The class of object entry being created. You can specify an application-defined class name. A class is specified as a simple name limited to 31 characters. value The version of the class assigned to the object entry. Specify the value as v.n, where v defines the major release number and n specifies the minor version number. Specifying a class version is useful as it allows the definition of a class to evolve as the application is revised. DESCRIPTION The create object command creates an object entry. This task is usually done through a client application. Privilege Required You must have insert permission to the parent directory. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command creates an object entry named /.:/sales/east/floor1cp. The object entry describes a color printer on the first floor of a company's eastern sales office. cdscp> create object /.:/sales/east/floor1cp CDS_Class = \ _> printer CDS_ClassVersion = 1.0 RELATED INFORMATION Commands: delete object list object set object show object 4 create_replica NAME create replica - Creates a replica of an existing directory in the specified clearinghouse SYNOPSIS cdscp create replica directory-name clearinghouse clearinghouse-name ARGUMENTS directory-name The full name of the directory. clearinghouse-name The full name of the clearinghouse in which you want to create the replica. DESCRIPTION The create replica command creates a replica of an existing directory in the specified clearinghouse. Privilege Required You must have administer permission to the directory you intend to replicate and write permission to the clearinghouse that stores the new replica. The server principal needs read, write, and administer permission to the directory you intend to replicate. NOTES This command is usually executed only by the network configuration procedure. To ensure that all replicas are consistent, perform an immediate skulk of the parent directory after issuing this command. This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command creates a replica of the /.:/mfg directory in the clearinghouse /.:/Paris_CH. cdscp> create replica /.:/mfg clearinghouse /.:/Paris1_CH RELATED INFORMATION Commands: delete replica show replica 4 define_cached_server NAME define cached server - Creates knowledge of a server in the local clerk's cache SYNOPSIS cdscp define cached server name tower value ARGUMENTS name A simple name for the cached server. value The protocol sequence and network address of the server node. The format is protocol-sequence:network-address. A protocol-sequence is a character string identifying the network protocols used to establish a relationship between a client and server. There are two choices of protocol sequence, depending on the network address that is supplied in the binding: ncacn_ip_tcp or ncadg_ip_udp. For the network-address, specify an Internet address using the common Internet address notation. For more information about this format, see the RPC introduction in the DCE Application Development Reference. DESCRIPTION The define cached server command creates knowledge of a server in the local clerk's cache. This command is typically used to manually provide configuration information to a clerk that cannot automatically configure itself. This is required, for instance, to give the clerk addressing information about a server across a WAN. Once the clerk knows about one server, it can find other servers through referrals. Privilege Required You must have write permission to the clerk. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES The following command creates knowledge of the server nrl in the local clerk's cache: cdscp> define cached server nrl tower ncacn_ip_tcp:16.20.15.25 RELATED INFORMATION Commands: clear cached server dump clerk cache show cached server Books: OSF DCE Application Development Reference 4 delete_child NAME delete child - Deletes a child pointer from the namespace SYNOPSIS cdscp delete child child-name ARGUMENTS child-name The full name of the child pointer. DESCRIPTION The delete child command deletes a child pointer from the namespace. Privilege Required You must have delete permission to the child pointer or administer permission to the parent directory. NOTES Use the delete child command only when the directory to which the child pointer refers is deleted and the child pointer accidentally remains. This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command deletes the child pointer that accidentally remains after the /.:/sales/east directory is deleted: cdscp> delete child /.:/sales/east RELATED INFORMATION Commands: create child list child show child 4 delete_clearinghouse NAME delete clearinghouse - Deletes the specified clearinghouse from the local server system SYNOPSIS cdscp delete clearinghouse clearinghouse-name ARGUMENT clearinghouse-name The full name of the clearinghouse. DESCRIPTION The delete clearinghouse command deletes a clearinghouse from the local server system. CDS does not permit you to delete a cleared clearinghouse. Before you can delete a cleared clearinghouse, you must recreate it using the create clearinghouse command. The delete clearinghouse command automatically deletes all read-only replicas from a clearinghouse. CDS does not permit you to delete a clearinghouse that contains a master replica. See the DCE Directory Service module of the DCE Administration Guide for more information about handling master replicas when deleting a clearinghouse. Permissions Required You must have write and delete permission to the clearinghouse and administer permission to all directories that store replicas in the clearinghouse. The server principal needs delete permission to the associated clearinghouse object entry and administer permission to all directories that store replicas in the clearinghouse. NOTES It is recommended that you delete all replicas except the root before issuing this command. This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command deletes a clearinghouse named /.:/sales/Orion_CH from the local server system: cdscp> delete clearinghouse /.:/sales/Orion_CH RELATED INFORMATION Commands: clear clearinghouse create clearinghouse list clearinghouse set cdscp preferred clearinghouse show clearinghouse show cdscp preferred clearinghouse Books: DCE Administration Guide 4 delete_directory NAME delete directory - Deletes a directory SYNOPSIS cdscp delete directory directory-name ARGUMENTS directory-name The full name of the directory. DESCRIPTION The delete directory command deletes a directory. The directory cannot contain any object entries, soft links, or child pointers. The master replica must be the only remaining replica in the cell. Use the delete replica command if you need to remove read-only replicas. Privilege Required You must have delete permission to the directory and write permission to the clearinghouse that stores the master replica of the directory. The server principal needs administer permission to the parent directory or delete permission to the child pointer that points to the directory you intend to delete. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command deletes the directory /.:/eng from the namespace: cdscp> delete directory /.:/eng RELATED INFORMATION Commands: create directory delete replica list directory set directory set directory to skulk show directory 4 delete_link NAME delete link - Deletes a soft link SYNOPSIS cdscp delete link link-name ARGUMENTS link-name The full name of the soft link. DESCRIPTION The delete link command deletes a soft link. Privilege Required You must have delete permission to the soft link, or administer permission to the directory that stores the soft link. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command deletes the soft link /.:/sales/asia. cdscp> delete link /.:/sales/asia RELATED INFORMATION Commands: create link list link set link show link 4 delete_object NAME delete object - Deletes an object entry SYNOPSIS cdscp delete object object-name ARGUMENTS object-name The full name of the object entry. DESCRIPTION The delete object command deletes an object entry. This task is usually done through the client application, except under certain circumstances (for example, if the application is obsolete or no longer has access to the namespace). Privilege Required You must have delete permission to the object entry, or administer permission to the directory that stores the object entry. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command deletes the object entry /.:/sales/east/floor1pr2. cdscp> delete object /.:/sales/east/floor1pr2 RELATED INFORMATION Commands: create object list object set object show object 4 delete_replica NAME delete replica - Deletes a read-only replica of a directory from a clearinghouse SYNOPSIS cdscp delete replica directory-name clearinghouse clearinghouse-name ARGUMENTS directory-name The full name of the directory clearinghouse-name The full name of the clearinghouse DESCRIPTION The delete replica command deletes a read-only replica of a directory from a clearinghouse. Use the delete directory command to delete the master replica of the directory. Privilege Required You must have administer permission to the directory whose replica you want to delete and write permission to the clearinghouse from which you are deleting the replica. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command deletes a read-only replica of the /.:/mfg directory from the /.:/Paris1_CH clearinghouse: cdscp> delete replica /.:/mfg clearinghouse /.:/Paris1_CH RELATED INFORMATION Commands: create replica delete directory show replica 4 disable_clerk NAME disable clerk - Stops the clerk on the local system SYNOPSIS cdscp disable clerk DESCRIPTION The disable clerk command stops the clerk on the local system, causing all active communication with any server to be aborted and all client calls in progress to fail. The clerk cache is copied to disk. Privilege Required You must have write permission to the clerk. NOTES If you are disabling a clerk on a system where a server is running, make sure you disable the server first. This command may be replaced in future releases by the dcecp command, and may no longer be supported at that time. EXAMPLES The following command stops the clerk on the local server system: cdscp> disable clerk RELATED INFORMATION Command: show clerk 4 disable_server NAME disable server - Stops the server on the local system SYNOPSIS cdscp disable server DESCRIPTION The disable server command stops the server on the local system. The server is disabled after all transactions in progress are completed. Privilege Required You must have write permission to the server. NOTE This command may be replaced in future releases by the dcecp command, and may no longer be supported at that time. EXAMPLE The following command stops the server on the local system: cdscp> disable server RELATED INFORMATION Command: show server 4 dump_clerk_cache NAME dump clerk cache - Displays the contents of the clerk cache SYNOPSIS cdscp dump clerk cache DESCRIPTION The dump clerk cache command displays the contents of the clerk cache on the screen. Use this command when solving CDS problems. Privilege Required You must have superuser (root) privileges on the clerk system. No CDS permissions are required. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command displays the contents of the clerk cache on the screen: cdscp> dump clerk cache RELATED INFORMATION Command: show clerk 4 list_child NAME list child - Displays a list of all the child pointers whose names match the specified child name SYNOPSIS cdscp list child child-name [with attribute-name = attribute-value] ARGUMENTS child-name The full name of a specific child pointer. The last simple name can contain wildcard characters. attribute-name The name of a particular attribute. attribute-value The value of a particular attribute. DESCRIPTION The list child command displays a list of all the child pointers whose names match the specified child name. The last simple name can contain wildcard characters. You can use a with attribute-name = attribute-value clause to limit output only to child pointers whose attributes have values equal to the specified values. A space must precede and follow the = (equals sign). Privilege Required You must have read permission to the directory that stores the child pointer. If you use a with attribute-name = attribute-value clause in the command, you also need read or test permission to the selected child pointers. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command displays a list of all the child pointers named in the /.:/sales directory: cdscp> list child /.:/sales/* LIST CHILD /.../abc.com/sales AT 1991-10-15-15:56:00 Q1 Q2 Q3 Q4 RELATED INFORMATION Commands: create child delete child show child 4 list_clearinghouse NAME list clearinghouse - Displays a list of all the clearinghouses whose names match the specified clearinghouse name SYNOPSIS cdscp list clearinghouse clearinghouse-name [with attribute-name = attribute-value] ARGUMENTS clearinghouse-name The full name of a specific clearinghouse. The last simple name can contain wildcard characters. attribute-name The name of a particular attribute. attribute-value The value of a particular attribute. DESCRIPTION The list clearinghouse command displays a list of all the clearinghouses whose names match the specified name. The last simple name can contain wildcards. You can use a with attribute-name = attribute-value clause to limit output only to clearinghouses whose attributes have values equal to the specified values. A space must precede and follow the = (equals sign). Privilege Required You must have read permission to the directory that stores the associated clearinghouse object entry. If you use a with attribute-name = attribute-value clause in the command, you also need read or test permission to the selected clearinghouses. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command displays a list of all the clearinghouses named in the root directory: cdscp> list clearinghouse /.:/* LIST CLEARINGHOUSE /.../abc.com/* AT 1991-10-15-15:56:00 /.../abc.com/Munich_CH /.../abc.com/Paris_CH RELATED INFORMATION Commands: clear clearinghouse create clearinghouse delete clearinghouse set cdscp preferred clearinghouse show cdscp preferred clearinghouse show clearinghouse 4 list_directory NAME list directory - Displays a list of all the directories whose names match the specified directory name SYNOPSIS cdscp list directory directory-name [with attribute-name = attribute-value] ARGUMENTS directory-name The full name of a specific directory. The last simple name can contain wildcard characters. attribute-name The name of a particular attribute. attribute-value The value of a particular attribute. DESCRIPTION The list directory command displays a list of all the directories whose names match the specified directory name. The last simple name can contain wildcards. You can use a with attribute-name = attribute-value clause to limit output only to directories whose attributes have values equal to the specified values. A space must precede and follow the = (equals sign). Privilege Required You must have read permission to the parent directory. If you use a with attribute-name = attribute-value clause in the command, you also need read or test permission to the selected directories. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command displays the names of all the directories in the /.:/sales directory: cdscp> list directory /.:/sales/* LIST DIRECTORY /.../abc.com/sales AT 1991-10-15-15:43:58 atlanta austin boston chicago ontario ny seattle RELATED INFORMATION Commands: add directory create directory delete directory remove directory set directory set directory to skulk show directory 4 list_link NAME list link - Displays a list of all the soft links whose names match the link name that you specify SYNOPSIS cdscp list link link-name [with attribute-name = attribute-value] ARGUMENTS link-name The full name of a specific soft link. The last simple name can contain wildcard characters. attribute-name The name of a particular attribute. attribute-value The value of a particular attribute. DESCRIPTION The list link command displays a list of all the soft links whose names match the link name that you specify. The last simple name can contain wildcard characters. You can use a with attribute-name = attribute-value clause to limit output only to soft links whose attributes have values equal to the specified values. A space must precede and follow the = (equals sign). This command does not list the name of the directory, object entry, or other soft link to which the soft link points. Privilege Required You must have read permission to the directory that stores the soft link. If you use a with attribute-name = attribute-value clause in the command, you also need read or test permission to the selected soft links. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command displays a list of all the soft links whose names begin with the letter l in the directory /.:/admin. cdscp> list link /.:/admin/l* LIST SOFTLINK /.../abc.com/admin AT 1991-10-15-15:54:38 lnk01 lnk02 lnk03 lnk04 lnk05 lnk06 RELATED INFORMATION Commands: create link delete link remove link set link show link 4 list_object NAME list object - Lists the specifies object entries (including clearinghouse object entries) SYNOPSIS cdscp list object object-name [with attribute-name = attribute-value] ARGUMENTS object-name The full name of a specific object entry. The last simple name can contain wildcard characters. attribute-name The name of a particular attribute. attribute-value The value of a particular attribute. DESCRIPTION The list object command displays a list of all the object entries (including clearinghouse object entries) whose names match the object entry name that you specify. The last simple name can contain wild- card characters. You can use a with attribute-name = attribute-value clause to limit output only to object entries whose attributes have values equal to the specified values. A space must precede and follow the = (equals sign). Privilege Required You must have read permission to the directory that stores the object entry. If you use a with attribute-name = attribute-value clause in the command, you also need read or test permission to the selected object entries. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command displays a list of all the object entries named in the directory /.:/eng. cdscp> list object /.:/eng/* LIST OBJECT /.../abc.com/eng AT 1991-10-15-15:53:06 juno test_stats work_disk1 work_disk2 RELATED INFORMATION Commands: add object create object delete object remove object set object show object 4 remove_directory NAME remove directory - Removes a value from a set-valued or single-valued attribute (including application-defined attributes) of a directory SYNOPSIS cdscp remove directory directory-name attribute-name [= attribute-value] ARGUMENTS directory-name The full name of the directory. attribute-name The name of a particular attribute. Specify only one attribute at a time. See the cds_attributes file for the list of attributes and corresponding data types that your application uses. attribute-value The value of a particular attribute. The value of an application-defined attribute is dependent on the type of attribute. DESCRIPTION The remove directory command removes a value from a set-valued or single-valued attribute (including application-defined attributes) of a directory. If you do not specify a value, the command removes the entire attribute. This command can delete attributes created by the add directory and set directory commands. Usually this task is performed through the client application. See the OSF DCE Administration Guide for more information about attributes. Privilege Required You must have write permission to the directory. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE To remove the value 1 from the user-defined, set-valued attribute dirregion of a directory named /.:/sales, follow these steps: 1. Read the cds_attributes file to check that the attribute dirregion is listed, as shown in the following display: OID LABEL SYNTAX 1.3.22.1.3.66 dirregion small 2. Enter the following command to remove the value 1 from the attribute dirregion. cdscp> remove directory /.:/sales dirregion = 1 RELATED INFORMATION Commands: add directory list directory set directory set directory to skulk show directory Books: OSF DCE Administration Guide 4 remove_link NAME remove link - Removes a soft link's timeout value attribute SYNOPSIS cdscp remove link link-name CDS_LinkTimeout ARGUMENTS link-name The full name of the soft link. DESCRIPTION The remove link command removes a soft link's timeout value attribute, CDS_LinkTimeout, causing the soft link to become permanent. Privilege Required You must have write permission to the soft link. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command removes the timeout value attribute of a soft link named /.:/eng/link01. cdscp> remove link /.:/eng/link01 CDS_LinkTimeout RELATED INFORMATION Commands: create link delete link list link set link show link 4 remove_object NAME remove object - Removes a value from a set-valued or single-valued attribute (including application-defined attributes) of an object entry SYNOPSIS cdscp remove object object-name attribute-name [= attribute-value] ARGUMENTS object name The full name of the object entry. attribute-name The name of a particular attribute. Specify only one attribute at a time. See the cds_attributes file for the list of attributes and corresponding data types that your application uses. attribute-value The value of a particular attribute. The value of an application-defined attribute is dependent on the type of attribute. DESCRIPTION The remove object command removes a value from a set-valued or single-valued attribute (including application-defined attributes) of an object entry. If you do not specify a value, the command removes the entire attribute. This command can delete attributes created by the add object and set object commands. Usually, this task is performed through the client application. See the OSF DCE Administration Guide for more information about attributes. Privilege Required You must have write permission to the object entry. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE To remove the value ps from the attribute printcap of an object entry named /.:/mlh/deskprinter, follow these steps: 1. Read the cds_attributes file to check that the attribute printcap is listed, as shown in the following display: OID LABEL SYNTAX 1.3.22.1.3.50 printcap char 2. Enter the following command to remove the value ps from the attribute printcap. cdscp> remove object /.:/mlh/deskprinter printcap = ps RELATED INFORMATION Commands: add object list object set object show object Books: OSF DCE Administration Guide 4 set_cdscp_confidence NAME set cdscp confidence - Sets the confidence level of clerk calls issued as a result of CDS control program commands SYNOPSIS cdscp set cdscp confidence = value ARGUMENTS value One of the following confidence levels: low, medium, or high. A low confidence level means the clerk obtains information from caches or the most convenient server. A medium level means the clerk obtains information directly from a server. A high level means the clerk obtains information only at master replicas. The initial value is medium. DESCRIPTION The set cdscp confidence command sets the confidence level of clerk calls issued as a result of CDS control program commands. You must use this command within the CDS control program. Exiting from the CDS control program removes the confidence level setting. You must reset the confidence level each time you enter the CDS control program. NOTE This command may be replaced in future releases by the dcecp command, and may no longer be supported at that time. EXAMPLE The following command sets the confidence level of clerk calls to high. $ cdscp cdscp> set cdscp confidence = high RELATED INFORMATION Command: show cdscp confidence 4 set_cdscp_preferred_clearinghouse NAME set cdscp preferred clearinghouse - Specifies a preferred clearing- house to use for satisfying read requests that result from CDS control program commands SYNOPSIS cdscp set cdscp preferred clearinghouse [clearinghouse-name] ARGUMENTS clearinghouse-name The full name of the preferred clearinghouse. If you omit this argument, the command causes CDS to revert to the default, which is to use any clearinghouse. DESCRIPTION The set cdscp preferred clearinghouse command specifies a preferred clearinghouse to use for satisfying read requests that result from CDS control program commands. You cannot specify a preferred clearing- house for making modifications, because these requests always use the master replica. You must use this command within the CDS control program. Exiting from the CDS control program removes the preferred clearinghouse setting. You must reset the preferred clearinghouse each time you enter the CDS control program. Permissions Required None NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command specifies /.:/Paris_CH as the preferred clearinghouse: $ cdscp cdscp> set cdscp preferred clearinghouse /.:/Paris_CH RELATED INFORMATION Command: show cdscp preferred clearinghouse 4 set_directory NAME set directory - Changes the value of a modifiable, single-valued attribute of a directory SYNOPSIS cdscp set directory directory-name attribute-name = attribute-value ARGUMENTS directory-name The full name of the directory. attribute-name The name of a particular attribute. Specify only one attribute at a time. See the cds_attributes file for the list of attributes and corresponding data types that your application uses. attribute-value The value of a particular attribute. The value of an application-defined attribute is dependent on the type of attribute. DESCRIPTION The set directory command changes the value of a modifiable, single-valued attribute of a directory. If the attribute does not exist, this command creates it. Usually, this task is performed through the client application. See the OSF DCE Administration Guide for more information about attributes. You can specify an application-defined attribute or the following attributes: CDS_Convergence = value Specifies the degree of consistency among replicas. By default, every directory inherits the convergence of its parent at creation time. The default setting on the root directory is medium. You can define one of the following for value: low CDS does not immediately propagate any updates. The next skulk distributes all updates that occurred since the previous skulk. Skulks occur at least once every 24 hours. medium CDS attempts to immediately propagate an update to all replicas. If the attempt fails, the software lets the next scheduled skulk make the replicas consistent. Skulks occur at least once every 12 hours. high CDS attempts to immediately propagate an update to all replicas. If that attempt fails (for example, if one of the replicas is unavailable), a skulk is scheduled for within one hour. Background skulks occur at least once every 12 hours. Use this setting temporarily and briefly because it uses extensive system resources. CDS_UpgradeTo = v.n Controls the upgrading of a directory from one version of CDS to another. By modifying this attribute, you can initiate the upgrading of a directory to a higher version of CDS. Specify the value as v.n, where v indicates the major version number and n specifies the minor version number. There is no default. Privilege Required You must have write permission to the directory. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES The following command sets a low convergence value on the /.:/mfg directory: cdscp> set directory /.:/mfg CDS_Convergence = low The following commands upgrades the directory version on the /.:/host directory: dcecp> directory modify /.:/host -add {CDS_UpgradeTO 1.2} -single dcecp> directory synchronize /.:/host RELATED INFORMATION Commands: create directory delete directory list directory remove directory set directory to skulk show directory Books: OSF DCE Administration Guide 4 set_directory_to_new_epoch NAME set directory to new epoch - Reconstructs a directory's replica set, allowing you to designate a new master replica or to exclude a replica SYNOPSIS cdscp set directory directory-name to new epoch master clearinghouse-name [readonly clearinghouse-name...] [exclude clearinghouse-name...] ARGUMENTS directory-name The full name of the directory. master clearinghouse-name ... The full name of the clearinghouse in which an individual replica is located. The first clearinghouse-name specifies where the master replica is stored. readonly clearinghouse-name ... Designates the replicas in the specified clearinghouses as read-only. exclude clearinghouse-name ... Excludes the replicas in the specified clearinghouses. DESCRIPTION The set directory to new epoch command reconstructs a directory's replica set, allowing you to designate a new master replica or to exclude a replica. You must list each existing replica and indicate whether an existing replica needs to be included in or excluded from the new replica set. You can include or exclude more than one replica. The ellipses (...) indicates that you can specify multiple clearinghouse names, separated by spaces. When you set a new epoch on a directory, you must disable the clearinghouse containing the replica that is being excluded. To do this, use the disable server command (if the server has more than one clearinghouse, all its clearinghouses will be disabled). Note that all clearinghouses that are not excluded must be enabled and available before you issue the disable server command. Privilege Required You must have administer permission to the directory, and the server principal needs administer, read, and write permission to the directory. When designating a new master replica, you also need write permission to the clearinghouse that stores the new master replica, and the server principal needs write permission to each clearinghouse where the replica type is changed to read-only. NOTE This command may be replaced in future releases by the dcecp command, and may no longer be supported at that time. EXAMPLE The following command sets a new epoch for the directory /.:/mfg. The master replica is in the clearinghouse /.:/Paris1_CH, and read-only replicas are in the clearinghouses /.:/Chicago1_CH, /.:/Seattle_CH, and /.:/NY1_CH. The new replica set excludes the replica in the clearinghouse /.:/NY1_CH. cdscp> set directory /.:/mfg to new epoch master /.:/Paris1_CH \ > readonly /.:/Chicago1_CH /.:/Seattle_CH exclude /.:/NY1_CH RELATED INFORMATION Commands: set directory to skulk show directory show replica 4 set_directory_to_skulk NAME set directory to skulk - Starts the skulk of a directory immediately SYNOPSIS cdscp set directory directory-name to skulk ARGUMENTS directory-name The full name of the directory. DESCRIPTION The set directory to skulk command starts the skulk of a directory immediately. The CDS control program prompt cdscp> does not return until the skulk is complete. The amount of time for the skulk to complete is dependent on the location, number, and availability of replicas of the directory. Privilege Required You must have administer, write, insert, or delete permission to the directory. The server principal needs administer, read, and write permission to the directory. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command initiates a skulk on the /.:/admin directory: cdscp> set directory /.:/admin to skulk RELATED INFORMATION Commands: add directory create directory delete directory list directory remove directory set directory to new epoch show directory 4 set_link NAME set link - Changes the value of a modifiable, single-valued attribute of a soft link SYNOPSIS cdscp set link link-name attribute-name = attribute-value ARGUMENTS link-name The full name of the soft link. attribute-name The name of the attribute to be modified. Specify only one attribute at a time. See Description for valid attribute names. attribute-value The value of a particular attribute. DESCRIPTION The set link command changes the value of a modifiable, single-valued attribute of a soft link. The following are valid attributes: CDS_LinkTarget = fullname Specifies the full name of the directory, object entry, or other soft link to which the soft link points. CDS_LinkTimeout = (expiration-time extension-time) Specifies a timeout value after which the soft link is either checked or deleted. The timeout value contains both an expiration time and an extension time. If a soft link expires and its target entry is deleted, the soft link is deleted. If the soft link still points to an existing entry, its life is extended by the expiration time. Specify expiration-time in the format yyyy-mm-dd-hh:mm:ss (year-month-day-hour:minute:second). Specify extension-time in the format ddd-hh:mm:ss (day-hour:minute:second). Privilege Required You must have write permission to the soft link. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command redirects a soft link named /.:/admin/work_disk from its current destination name, /.:/admin/work_disk01, to a new destination name, /.:/admin/work_disk03. cdscp> set link /.:/admin/work_disk CDS_LinkTarget = \ _> /.:/admin/work_disk03 RELATED INFORMATION Commands: create link delete link list link show link 4 set_object NAME set object - Changes the value of a modifiable, single-valued attribute of an object entry SYNOPSIS cdscp set object object-name attribute-name = attribute-value ARGUMENTS object-name The full name of the object entry. attribute-name The name of the attribute to be modified. Specify only one attribute at a time. See the cds_attributes file for the list of attributes and corresponding data types that your application uses. attribute-value The value of a particular attribute. The value of an application-defined attribute is dependent on the type of attribute. DESCRIPTION The set object command changes the value of a modifiable,single-valued attribute of an object entry. If the attribute does not exist, this command creates it. Usually, this task is performed through the client application. See the OSF DCE Administration Guide for more information about attributes. Privilege Required You must have write permission to the object entry. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE To change the value of the sales_record attribute to region2 of an object entry named /.:/Q1_records, follow these steps: 1. Read the cds_attributes file to check that the attribute sales_record is listed, as shown in the following display: OID LABEL SYNTAX 1.3.22.1.3.66 sales_record char 2. Enter the following command to assign the value region2 to the attribute sales_record of an object entry named /.:/Q1_records. cdscp> set object /.:/Q1_records sales_record = region2 RELATED INFORMATION Commands: add object create object delete object list object remove object show object Books: OSF DCE Administration Guide 4 show_cached_clearinghouse NAME show cached clearinghouse - Displays current information about the specified cached clearinghouse SYNOPSIS cdscp show cached clearinghouse clearinghouse-name ARGUMENT clearinghouse-name A specific clearinghouse name. The name can contain wildcard characters. DESCRIPTION The show cached clearinghouse command displays all the names and values of the attributes in the specified cached clearinghouse. The following are valid attributes: Creation Time Specifies the time at which this clearinghouse was added to the cache Miscellaneous Operations Specifies the number of operations other than read and write (that is, skulks, new epochs, and so on) performed by this clerk on the cached clearinghouse Read Operations Specifies the number of lookup operations of any sort performed by the clerk on the cached clearinghouse Towers Specifies the protocol sequence and Internet address of the server that maintains the cached clearinghouse Write Operations Specifies the number of write operations performed by this clerk on the cached clearinghouse Privilege Required You must have read permission to the clerk. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command displays all attributes of the cached clearinghouse /.:/Paris2_CH. cdscp> show cached clearinghouse /.:/Paris2_CH SHOW CACHED CLEARINGHOUSE /.../abc.com/Paris2_CH AT 1991-10-15-15:58:09 Creation Time = 1991-10-01-17:03:32.32 Read Operations = 412 Write Operations = 618 Miscellaneous Operations = 278 RELATED INFORMATION Commands: list clearinghouse 4 show_cached_server NAME show cached server - Displays address information of a server in the local clerk's cache SYNOPSIS show cached server name ARGUMENTS name A simple name for the cached server. The name can contain wildcard characters. DESCRIPTION The show cached server command displays address information of a server in the local clerk's cache. The following list describes the valid attributes: Name The directory cell name Towers The protocol sequence and network address of the server node Privilege Required You must have read permission to the clerk. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES The following command displays all attributes of the cached server emv: cdscp> show cached server emv* SHOW CACHED NAMESERVER emv_udp AT 1991-10-15-15:56:56 Name = /.../emv.abc.com Tower = ncadg_ip_udp:14.20.14.32 Tower = ncacn_ip_tcp:14.20.14.32 SHOW CACHED NAMESERVER emv_tcp AT 1991-10-15-15:56:57 Name = /.../emv.abc.com Tower = ncadg_ip_udp:14.20.14.32 Tower = ncacn_ip_tcp:14.20.14.32 RELATED INFORMATION Commands: clear cached server define cached server 4 show_cdscp_confidence NAME show cdscp confidence - Displays the current confidence level of clerk calls resulting from CDS control program commands SYNOPSIS cdscp show cdscp confidence DESCRIPTION The show cdscp confidence command displays the current confidence level of clerk calls. A low confidence level means the clerk obtains information from caches or the most convenient server. A medium level means the clerk obtains information directly from a server. A high level means the clerk obtains information only at master replicas. You must use this command within the CDS control program. Exiting from the CDS control program removes the confidence level setting. You must reset the confidence level each time you enter the CDS control program. NOTE This command may be replaced in future releases by the dcecp command, and may no longer be supported at that time. EXAMPLE The following command displays the current confidence level of clerk calls: $ cdscp cdscp> show cdscp confidence Confidence used is medium RELATED INFORMATION Commands: set cdscp confidence 4 show_cdscp_preferred_clearinghouse NAME show cdscp preferred clearinghouse - Displays the preferred clearinghouse for satisfying read requests that result from CDS control program commands SYNOPSIS cdscp show cdscp preferred clearinghouse DESCRIPTION The show cdscp preferred clearinghouse command displays the preferred clearinghouse for satisfying read requests that result from CDS control program commands. You can only read attribute values for entries stored in the specified clearinghouse. You must use this command within the CDS control program. Exiting from the CDS control program removes the preferred clearinghouse setting. You must reset the preferred clearinghouse each time you enter the CDS control program. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command displays the current clearinghouse: $ cdscp cdscp> show cdscp preferred clearinghouse read attribute values from clearinghouse /.../abc.com/Paris_CH RELATED INFORMATION Commands: set cdscp preferred clearinghouse 4 show_cell NAME show cell - Displays the information you need to create a cell entry in either DNS or GDS SYNOPSIS cdscp show cell cell-name [as type] ARGUMENTS cell-name The global name of the cell. type The global namespace in which you want to define the cell. Enter either of the values dns or gds. The default is gds. DESCRIPTION The show cell command displays the information you need to create a cell entry in either the Domain Name System (DNS) or the Global Directory Service (GDS). DCE does not support cells registered simultaneously in GDS and DNS. If you want to define a cell in DNS, you can use this command to produce a preformatted set of resource records. You can then edit the appropriate DNS data file and copy the output directly into the file. In GDS, cell information is contained in two attributes: CDS-Cell and CDS-Replica. If you want to define a cell in GDS, you can use this command to obtain the data you need to supply when creating the CDS-Cell and CDS-Replica attributes. For details, see the OSF DCE Administration Guide. Privilege Required You must have read permission to the cell root directory. NOTE This command may be replaced in future releases by the dcecp command, and may no longer be supported at that time. EXAMPLES The following command displays the GDS-formatted output in the local cell: cdscp> show cell /.../abc.com as gds SHOW CELL /.../abc.com AT 1991-10-15-15:58:25 Namespace Uuid = 2d2d50ad-8b1a-11ba-8983-08002b0f79aa Clearinghouse Uuid = 2ab024a8-8b1a-11ba-8983-08002b0f79aa Clearinghouse Name = /.../abc.com/NY_CH Replica Type = Master Tower 1 = ncadg_ip_udp:16.18.17.33 Tower 2 = ncacn_ip_tcp:16.18.17.33 Namespace Uuid = 2d2d50ad-8b1a-11ba-8983-08002b0f79aa Clearinghouse Uuid = 49757f28-8b1a-11ba-8983-08002b0f79aa Clearinghouse Name = /.../abc.com/Boston_CH Replica Type = Readonly Tower 1 = ncadg_ip_udp:16.18.17.33 Tower 2 = ncacn_ip_tcp:16.18.17.33 RELATED INFORMATION Books: OSF DCE Administration Guide 4 show_child NAME show child - Displays attribute information about the specified child pointer SYNOPSIS cdscp show child child-name [attribute-name] [with attribute-name = attribute-value] ARGUMENTS child-name The full name of a specific child pointer. The last simple name can contain wildcard characters. attribute-name The name of an attribute; see Description for valid attribute names. attribute-value The value of a particular attribute. DESCRIPTION The show child command displays the names and values of the attributes specified in attribute-name. You can use a combination of attributes in a single command. Use a space to separate multiple attributes. You can use a with attribute-name = attribute-value clause to limit output only to child pointers whose attributes have values equal to the specified values. A space must precede and follow the = (equals sign). If you do not supply any attributes, the command displays all attributes and their values. The following is a description of child pointer attributes: CDS_CTS Specifies the creation timestamp (CTS) of the specified child pointer. CDS_ObjectUUID Specifies the unique identifier of the directory to which the child pointer refers. CDS_Replicas Specifies the address, UUID, and name of a set of clearinghouses where a copy of the child directory referenced by the child pointer is located. This attribute also specifies whether the directory in a particular clearinghouse is a master or read-only replica. CDS_UTS Specifies the timestamp of the most recent update to an attribute of the child pointer. Privilege Required You must have read permission to the child pointer. If you specify a wildcard child name, you also need read permission to the parent directory. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command displays all of the attributes and values of the child directory to which the child pointer /.:/admin refers: cdscp> show child /.:/admin SHOW CHILD /.../abc.com/admin AT 1991-10-15-15:56:01 CDS_CTS = 1991-10-15-19:55:52.000000003/08-00-2b-1c-8f-1f CDS_UTS = 1991-10-15-19:55:52.000000006/08-00-2b-1c-8f-1f CDS_ObjectUUID = 6b5362e8-8b1c-11ca-8981-08002b0f79aa CDS_Replicas = : Clearinghouse's UUID = 2ab024a8-8b1a-11ca-8981-08002b0f79aa Tower = ncadg_ip_udp:16.18.16.32 Tower = ncacn_ip_tcp:16.18.16.32 Replica type = master Clearinghouse's Name = /.../abc.com/Boston_CH RELATED INFORMATION Commands: create child delete child list child 4 show_clearinghouse NAME show clearinghouse - Displays attribute information about the specified clearinghouse SYNOPSIS cdscp show clearinghouse clearinghouse-name [attribute-name] [with attribute-name = attribute-value] ARGUMENTS clearinghouse-name The full name of a specific clearinghouse. The last simple name can contain wildcard characters. attribute-name The name of a particular attribute; see Description for valid attribute names. attribute-value The value of a particular attribute. DESCRIPTION The show clearinghouse command displays the names and values of the attributes specified in attribute-name. You can use a combination of attributes in any sequence in a single command. Use a space to separate multiple attributes. You can use a with attribute-name = attribute-value clause to limit output only to clearinghouses whose attributes have values equal to the specified values. A space must precede and follow the = (equals sign). If you do not supply any attributes, the command displays all attributes and their values. The following list describes the clearinghouse attributes: CDS_AllUpTo Indicates the date and time the clearinghouse object has been updated to reflect the CDS_CHDirectories attribute. CDS_CHDirectories Specifies the full name and unique identifier (UUID) of every directory that has a replica in this clearinghouse. CDS_CHLastAddress Specifies the current reported network address of the clearinghouse. CDS_CHName Specifies the full name of the clearinghouse. CDS_CHState Specifies the state of the clearinghouse. The state on indicates the clearinghouse is running and available. CDS_NSCellname Specifies the name of the cell in which the clearinghouse resides. CDS_CTS Specifies the creation timestamp (CTS) of the clearinghouse. CDS_DirectoryVersion Specifies the directory version for new directories that are created in the clearinghouse. CDS_ObjectUUID Specifies the unique identifier of the clearinghouse. CDS_ReplicaVersion Specifies the current version of the replica in which the directory was created. CDS_UTS Specifies the timestamp of the most recent update to an attribute of the clearinghouse. The following counters and their values are displayed only when you use this command to display all attributes and their values: Data Corruption Count Specifies the number of times that the data corruption event was generated Enables Specifies the number of times that the clearinghouse was enabled since it was last started Read Accesses Specifies the number of read operations directed to this clearinghouse References Returned Specifies the number of requests directed to this clearinghouse that resulted in the return of a partial answer instead of satisfying the client's request Skulk Failures Specifies the number of times that a skulk of a directory, initiated from this clearinghouse, failed to complete - usually because one of the replicas in the replica set was unreachable Entry Missing Count Specifies the number of times the clearinghouse entry missing event was generated Root Not Reachable Count Specifies the number of times the root lost event was generated Upgrades Failed Counts Specifies the number of times that upgrades failed Write Accesses Specifies the number of write operations directed to this clearinghouse Disables Specifies the number of times that the clearinghouse was disabled since it wsa last started Privilege Required You must have read permission to the clearinghouse. If you specify a wildcard clearinghouse name, you also need read permission to the cell root directory. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command displays the current values of the CDS_UTS and CDS_ObjectUUID attributes associated with the /.:/Chicago1_CH clearinghouse: cdscp> show clearinghouse /.:/Chicago1_CH CDS_UTS CDS-ObjectUUID SHOW CLEARINGHOUSE /.../abc.com/Chicago1_CH AT 1991-10-21-13:12:30 CDS_UTS = 1991-10-21-13:04:04.000000009/08-00-2b-1c-8f-1f CDS_ObjectUUID = 3706d70c-8b05-11ca-9002-08002b1c8f1f RELATED INFORMATION Commands: clear clearinghouse create clearinghouse delete clearinghouse list clearinghouse set cdscp preferred clearinghouse show cdscp preferred clearinghouse 4 show_clerk NAME show clerk - Displays attribute information about the CDS clerk on the local system SYNOPSIS cdscp show clerk DESCRIPTION The show clerk command displays all the names and values of the clerk attributes on the local system. The clerk must be enabled when you use this command. The following are valid attributes: Authentication Failures Specifies the number of times a requesting principal failed authentication procedures. Cache Bypasses Specifies the number of requests to read attributes for which the clerk was specifically directed by the requesting application to bypass its own cache. Instead, a server is contacted to get the requested information. This attribute does not account for requests that the clerk is unable to satisfy from the cache or for requests to look up names or enumerate the contents of directories. Cache Hits Specifies the total number of read requests directed to this clerk that were satisfied entirely by the information contained in its own cache. This attribute accounts only for requests to read attribute values and does not include requests to look up names or enumerate the contents of directories. Creation Time Specifies the time when this entity was created. Miscellaneous Operations Specifies the number of operations other than read and write (that is, skulks, enumerating contents of directories, and so on) performed by this clerk. Read Operations Specifies the number of lookup operations performed by this clerk. This attribute accounts only for requests to read attributes and does not include requests to look up names or enumerate the contents of directories. Write Operations Specifies how many requests to modify data were processed by this clerk. Privilege Required You must have read permission to the clerk. NOTE This command may be replaced in future releases by the dcecp command, and may no longer be supported at that time. EXAMPLE The following command displays the attributes of the clerk on the local system: cdscp> show clerk SHOW CLERK AT 1991-10-15-15:56:50 Creation Time= 1991-10-15-15:38:19.000000051-04:00I0.000000000 Authentication failures= 0 Read Operations= 1068 Cache Hits= 137 Cache bypass = 433 Write operations= 1250 Miscellaneous operations= 590 RELATED INFORMATION Commands: disable clerk 4 show_directory NAME show directory - Displays attribute information about the specified directory SYNOPSIS cdscp show directory directory-name [attribute-name] [with attribute-name = attribute-value] ARGUMENTS directory-name The full name of a specific directory. The last simple name can contain wildcard characters. attribute-name The name of a particular attribute; see Description for valid attribute names. attribute-value The value of a particular attribute. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. RELATED INFORMATION Commands: add directory create directory delete directory list directory remove directory set directory 5 DESCRIPTION The show directory command displays the names and values of the attributes specified in attribute-name. You can use a combination of attributes in any sequence in a single command. Use a space to separate multiple attributes. You can use a with attribute-name = attribute-value clause to limit output only to directories whose attributes have values equal to the specified values. A space must precede and follow the = (equals sign). If you do not supply any attributes, the command displays all attributes and their values. In addition to the following directory attributes, application-specific attributes can exist for a directory: CDS_AllUpTo Indicates the date and time of the last successful skulk on the directory. All replicas of the directory are guaranteed to receive all updates whose timestamps are less than the value of this attribute. CDS_Convergence Specifies the degree of consistency among replicas. This attribute's value is defined as one of the following: low CDS does not immediately propagate an update. The next skulk distributes all updates that occurred since the previous skulk. Skulks occur at least once every 24 hours. medium CDS attempts to immediately propagate an update to all replicas. If the attempt fails, the next scheduled skulk makes the replicas consistent. Skulks occur at least once every 12 hours. high CDS attempts to immediately propagate an update to all replicas. If the attempt fails (for example, if one of the replicas is unavailable), a skulk is scheduled for within one hour. Skulks usually occur at least once every 12 hours. Use this setting temporarily and briefly, because it uses extensive system resources. By default, every directory inherits the convergence setting of its parent at creation time. The default setting on the root directory is medium. CDS_CTS Specifies the creation timestamp (CTS) of the CDS directory. CDS_DirectoryVersion Specifies the minimum of all the values of the CDS_ReplicaVersion attribute on the directory replicas. CDS_Epoch A UUID that identifies a particular incarnation of the directory. CDS_LastSkulk Records the timestamp of the last skulk performed on this directory. CDS_LastUpdate Records the timestamp of the most recent change to any attribute of a directory replica,or any change to an entry in the replica. CDS_ObjectUUID Specifies the unique identifier of the directory. CDS_ParentPointer Contains a pointer to this directory's parent in the namespace. CDS_Replicas Specifies the address, UUID, and name of every clearinghouse where a copy of this directory is located. This attribute also specifies whether the replica in a particular clearinghouse is a master or read-only replica. CDS_ReplicaState Specifies whether a directory replica can be accessed. CDS_ReplicaType Indicates whether a directory replica is a master or read-only replica. CDS_ReplicaVersion Specifies the version of a replica of the directory. CDS_RingPointer Specifies the UUID of a clearinghouse containing another replica of this directory. This attribute is written by the system and is read-only to users. It will appear on older directories, but not on DCE 1.1 directories. CDS_UpgradeTo Controls the upgrading of a directory from one version of CDS to another. By modifying this attribute, you can initiate the upgrading of a directory to a new version of CDS. CDS_UTS Specifies the timestamp of the most recent update to an attribute of the directory. RPC_ClassVersion Specifies the RPC runtime software version that can be used to import on the directory. Privilege Required You must have read permission to the directory. If you specify a wildcard directory name, you also need read permission to the directory's parent directory. 5 EXAMPLE The following command displays the current values of all the attributes associated with the /.:/admin directory: cdscp> show directory /.:/admin SHOW DIRECTORY /.../abc.com/admin AT 1991-10-15-15:43:59 RPC_ClassVersion = 0100 CDS_CTS = 1991-10-15-13:09:47.000000003/08-00-2b-1c-8f-1f CDS_UTS = 1991-10-17-08:59:50.000000006/08-00-2b-1c-8f-1f CDS_ObjectUUID = ba700c98-8b1a-11ca-8981-08002b0f79aa CDS_Replicas = : Clearinghouse's UUID = 2ab024a8-8b1a-11ca-8981-08002b0f79aa Tower = ncadg_ip_udp:16.20.16.32 Tower = ncacn_ip_tcp:16.20.16.32 Replica type = master Clearinghouse's Name = /.../abc.com/Paris_CH CDS_AllUpTo = 1991-10-17-08:51:18.000000032/08-00-2b-1c-8f-1f CDS_Convergence = medium CDS_ParentPointer = : Parent's UUID = b773525c-8b1a-11ca-8981-08002b0f79aa Timeout = : Expiration = 1991-10-16-19:43:50.516 Extension = +1-00:00:00.000 CDS_DirectoryVersion = 3.0 CDS_ReplicaState = on CDS_ReplicaType = master CDS_LastSkulk = 1991-10-17-08:51:18.000000032/08-00-2b-1c-8f-1f CDS_LastUpdate = 1991-10-21-13:04:02.000000044/08-00-2b-1c-8f-1f CDS_RingPointer = 2ab024a8-8b1a-11ca-8981-08002b0f79aa CDS_Epoch = bd8b2c50-8b1a-11ca-8981-08002b0f79aa CDS_ReplicaVersion = 3.0 4 show_link NAME show link - Displays attribute information about the specified soft link SYNOPSIS cdscp show link link-name [attribute-name] [with attribute-name = attribute-value] ARGUMENTS link-name The full name of a specific soft link. The last simple name can contain wildcard characters. attribute-name The name of a particular attribute; see Description for valid attribute names. attribute-value The value of a particular attribute. DESCRIPTION The show link command displays the names and values of the attributes specified in attribute-name. You can use a combination of attributes in any sequence in a single command. Use a space to separate multiple attributes. You can use a with attribute-name = attribute-value clause to limit output only to soft links whose attributes have values equal to the specified values. A space must precede and follow the = (equals sign). If you do not supply any attributes, the command displays all attributes and their values. The following is a description of soft link attributes: CDS_CTS Specifies the creation timestamp (CTS) of this soft link CDS_LinkTarget Specifies the full name of the directory, object entry, or other soft link to which the soft link points CDS_LinkTimeout Specifies a timeout value after which the soft link is either checked or deleted CDS_UTS Specifies the timestamp of the most recent update to an attribute of the soft link Privilege Required You must have read permission to the soft link. If you specify a wildcard soft link name, you also need read permission to the directory that stores the soft link. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command displays the current values of all the attributes associated with the soft link /.:/sales/region1. cdscp> show link /.:/sales/region1 SHOW SOFTLINK /.../abc.com/sales/region1 AT 1991-10-15-15:54:40 CDS_CTS = 1991-10-15-19:54:35.00000003/08-00-2b-1c-8f-1f CDS_UTS = 1991-10-15-19:54:35.00000006/08-00-2b-1c-8f-1f CDS_LinkTarget = /.../abc.com/sales/service SHOW SOFTLINK /.../abc.com/sales/region1 AT 1991-10-15-15:54:41 CDS_CTS = 1991-10-15-19:54:36.00000077/08-00-2b-1c-8f-1f CDS_UTS = 1991-10-15-19:54:36.00000009/08-00-2b-1c-8f-1f CDS_LinkTarget = /.../abc.com/sales/software CDS_LinkTimeout = : Expiration = 1991-10-15-00:00:00.0 Extension = +1-00:00:00.000 RELATED INFORMATION Commands: create link delete link list link remove link set link 4 show_object NAME show object - Displays attribute information about the specified object entry SYNOPSIS cdscp show object object-name [attribute-name] [with attribute-name = attribute-value] ARGUMENTS object-name The full name of a specific object entry. The last simple name can contain wildcard characters. attribute-name The name of a particular attribute; see Description for valid attribute names. attribute-value The value of a particular attribute. DESCRIPTION The show object command displays the names and values of the attributes specified in attribute-name. You can use a combination of attributes in a single command. Use a space to separate multiple attributes. You can use a with attribute-name = attribute-value clause to limit output only to object entries whose attributes have values equal to the specified values. If you do not supply any attributes, the command displays all attributes and their values. In addition to the following attributes, any application-defined attributes that might exist will be included in the output of this command. The following is a description of object entry attributes: CDS_Class Specifies the class to which an object belongs. CDS_ClassVersion Contains the version number of the object's class. This allows applications to build in compatibility with entries created by earlier versions. CDS_CTS Specifies the creation timestamp (CTS) of this object entry. CDS_ObjectUUID Specifies a unique identifier for the object being referenced. CDS_UTS Specifies the timestamp of the most recent update to an attribute of the object entry. Privilege Required You must have read permission to the object entry. If you specify a wildcard object entry name, you also need read permission to the directory that stores the object entry. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE The following command lists all the attributes and their values of the object entry /.:/sales/east/floor1cp. cdscp> show object /.:/sales/east/floor1cp SHOW OBJECT /.../abc.com/sales/floor1cp AT 1991-10-15-15:53:07 CDS_CTS = 1991-10-15-19:53:03.00000003/08-00-2b-1c-8f-1f CDS_UTS = 1991-10-15-19:53:03.00000006/08-00-2b-1c-8f-1f RELATED INFORMATION Commands: add object create object delete object list object remove object set object 4 show_replica NAME show replica - Displays attribute information about the specified replica SYNOPSIS cdscp show replica directory-name clearinghouse clearinghouse-name [attribute-name] ARGUMENTS directory-name The full name of the directory clearinghouse-name The full name of the clearinghouse attribute-name The name of a particular attribute; see Description for valid attribute names. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. RELATED INFORMATION Commands: create replica delete replica 5 DESCRIPTION The show replica command displays the directory-specific attributes as well as the per-replica attributes of the specified directory. If you do not supply any attributes, the command displays all attributes and their values; any application-defined attributes that might exist will be included in the output of this command. You can enter one or more of the following attributes: CDS_AllUpTo Indicates the date and time of the last successful skulk on the directory. All replicas of the directory are guaranteed to have received all updates whose timestamps are less than the value of this attribute. CDS_Convergence Specifies the degree of consistency among replicas. This attribute's value is defined as one of the following: low CDS does not immediately propagate an update. The next skulk distributes all updates that occurred since the previous skulk. Skulks occur at least once every 24 hours. medium CDS attempts to immediately propagate an update to all replicas. If the attempt fails, the next scheduled skulk makes the replicas consistent. Skulks occur at least once every 12 hours. high CDS attempts to immediately propagate an update to all replicas. If the attempt fails (for example, if one of the replicas is unavailable), a skulk is scheduled for within one hour. Skulk usually occur at least once every 12 hours. Use this setting temporarily and briefly,because it uses extensive system resources. By default, every directory inherits the convergence setting of its parent at creation time. The default setting on the root directory is medium. CDS_CTS Specifies the creation timestamp (CTS) of the directory of which this replica is a copy. CDS_DirectoryVersion Specifies the minimum of all the values of the CDS_ReplicaVersion attribute on the directory replicas. CDS_Epoch A UUID that identifies a particular incarnation of the directory. CDS_LastSkulk Records the timestamp of the last skulk performed on this particular replica of a directory. CDS_LastUpdate Records the timestamp of the last update to any attribute of the replica, or any change to the contents of the replica,including object entries,child pointers,and soft links. CDS_ObjectUUID Specifies the unique identifier of the directory of which this replica is a copy. CDS_ParentPointer Contains a pointer to this directory's parent in the namespace. CDS_Replicas Specifies the address, UUID, and name of every clearinghouse where a replica of this directory is located. This attribute also specifies whether the replica in a particular clearinghouse is a master or read-only replica. CDS_ReplicaState Specifies the internal state of a replica. When you create or delete a replica, it goes through various states. CDS_ReplicaType Specifies the replica type of a directory. CDS_ReplicaVersion Specifies the replica version of a directory. CDS_RingPointer Specifies the UUID of a clearinghouse containing another replica of this directory. This attribute is written by the system and is read-only to users. It will appear on older directories, but not on DCE 1.1 directories. CDS_UTS Specifies the timestamp of the most recent update to an attribute of the directory. RPC_ClassVersion Specifies the RPC runtime software version that can be used to import on the directory. Privilege Required You must have read permission to the directory from which the replica is created. 5 EXAMPLE The following command displays the current values of all the attributes of the replica of the /.:/eng directory in the /.:/Chicago2_CH clearinghouse: cdscp> show replica /.:/eng clearinghouse /.:/Chicago2_CH SHOW REPLICA /.../abc.com/eng AT 1991-10-15-15:55:29 RPC_ClassVersion = 0100 CDS_CTS = 1991-10-15-12:09:47.000000003/08-00-2b-1c-8f-1f CDS_UTS = 1991-10-17-07:59:50.000000006/08-00-2b-1c-8f-1f CDS_ObjectUUID = 5816da70-8b1c-11ca-8981-08002b0f79aa CDS_Replicas = : Clearinghouse's UUID = 2ab024a8-8b1a-11ca-8981-08002b0f79aa Tower = ncadg_ip_udp:16.20.16.32 Tower = ncacn_ip_tcp:16.20.16.32 Replica type = master Clearinghouse's Name = /.../abc.com/Chicago1_CH CDS_Replicas = : Clearinghouse's UUID = 49757f28-8b1a-11ca-8981-08002b0f79aa Tower = ncadg_ip_udp:16.20.16.32 Tower = ncacn_ip_tcp:16.20.16.32 Replica type = readonly Clearinghouse's Name = /.../abc.com/Chicago2_CH CDS_AllUpTo = 1991-10-17-07:51:18.000000032/08-00-2b-1c-8f-1f CDS_Convergence = medium CDS_ParentPointer = : Parent's UUID = 560f1ad0-8b1c-11ca-8981-08002b0f79aa Timeout = : Expiration = 1991-10-15-19:55:18.711 Extension = +1-00:00:00.000 CDS_DirectoryVersion = 3.0 CDS_ReplicaState = on CDS_ReplicaType = readonly CDS_LastSkulk = 1991-10-17-07:51:18.000000032/08-00-2b-1c-8f-1f CDS_LastUpdate = 1991-10-21-12:04:02.000000044/08-00-2b-1c-8f-1f CDS_RingPointer = 2ab024a8-8b1a-11ca-8981-08002b0f79aa CDS_Epoch = 58472144-8b1c-11ca-8981-08002b0f79aa CDS_ReplicaVersion = 3.0 4 show_server NAME show server - Displays attribute information about the server running on the local system SYNOPSIS cdscp show server DESCRIPTION The show server command displays all the names and values from the attributes named in this entity. The server must be enabled when you use this command. The following are valid attribute names: Child Update Failures Specifies the number of times the server was unable to contact all the clearinghouses that store a replica of a particular child directory's parent directory and apply the child updates that have occurred since the last skulk. This counter is incremented by the Cannot Update Child Pointer event. Creation Time Specifies the time when the CDS control program process was started. Crucial Replicas Specifies the number of times a user attempted (from this server) to remove a replica that is crucial to the connectivity of a directory hierarchy. The server background process prevents users from accidentally disconnecting lower-level directories from higher-level directories. When it detects an attempt to remove a crucial replica, it does not execute the command to do so. This counter is incremented by the Crucial Replica event. Future Skew Time Specifies the maximum amount of time that a timestamp on a new or modified entry can vary from local system time at the server system. Known Clearinghouses Specifies the clearinghouse or clearinghouses known to the server. Read Operations Specifies the number of read operations directed to this CDS server. Security Failures Specifies the number of times a server principal for this server was found to have inadequate permissions to perform a requested operation. Skulks Completed Specifies the number of skulks successfully completed by this CDS server. Skulks Initiated Specifies the number of skulks initiated by this CDS server. Times Lookup Paths Broken Specifies the number of broken connections between clearinghouses on this server and clearinghouses closer to the root. Incoming requests to this server that require a downward lookup in the directory hierarchy still succeed, but requests that require a lookup in directories closer to the root will fail. This counter is incremented by the Broken Lookup Paths event. Write Operations Specifies the number of write operations to this CDS server. Privilege Required You must have read permission to the server. NOTE This command may be replaced in future releases by the dcecp command, and may no longer be supported at that time. EXAMPLE The following command displays the current values of all the attributes associated with the server running on the local system: cdscp> show server SHOW SERVER AT 1991-10-15-15:56:47 Creation Time = 1991-10-15-15:39:35.35 Future Skew Time = 300 Read Operations = 757 Write Operations = 542 Skulks Initiated = 219 Skulks Completed = 219 Times Lookup Paths Broken = 1 Crucial Replicas = 0 Child Update Failures = 1 Security Failures = 0 Known Clearinghouses = /.../abc.com/Boston_CH = /.../abc.com/NY_CH RELATED INFORMATION Command: disable server 3 cdsbrowser NAME cdsbrowser - Starts the CDS Browser utility on the local system SYNOPSIS cdsbrowser DESCRIPTION The cdsbrowser command starts the CDS Browser utility on the local system. This utility runs on workstations with windowing software based on the OSF/Motif graphical user interface. Using a mouse to manipulate pull-down menus, you can view the directory structure of a namespace, view child directories of a particular directory, view the object entries and soft links in a directory, and set a filter to display only object entries of a particular class. (For users who do not have windowing software, similar functions are available with the control program.) When you use the CDS Browser, it sets the confidence level of clerk calls to low. Privilege Required None EXAMPLE The following command starts the CDS Browser utility on the local system: $ cdsbrowser If the cdsbrowser command is not currently defined, execute the following command file, and try again: $ @sys$manager:dce$define_required_commands RELATED INFORMATION Books: OSF DCE Administration Guide 3 cdsclerk NAME cdsclerk - Manages the interface between clients and the CDS server SYNOPSIS cdsclerk [-D] [-w route] OPTIONS -D For debugging use only. -w route Routes serviceability messages. DESCRIPTION The cdsclerk command manages the interface between clients and the CDS server. Privilege Required Your UIC must be DCE$SERVER. NOTES You should use this command interactively only to do diagnostic work on the host system. EXAMPLE Before you run the following process, make sure that other clerks are not running. To start the cdsclerk process for debugging, follow these steps: 1. Make sure that a CDS server is already running somewhere within the cell. 2. Log in to the system as a privileged user, and set your UIC to DCE$SERVER. 3. Log in to DCE as the machine principal of the local host. Enter the principal name in the format /hosts/hostname/self as shown in the following example command for a host named orion whose password is smith: $ dce_login hosts/orion/self smith 4. Enter the following command to see if the dced process is already running: $ show system If the DCE$DCED process appears on the list of active processes, proceed to step 5. If the DCE$DCED process does not appear on the list of active processes, enter the following command to start the process (for debugging only): $ r sys$system:dce$dced 5. Enter the following command to start the cdsadv process: $ r sys$system:dce$cdsadver 6. Enter the following command with the appropriate arguments to start the cdsclerk process: $ r sys$system:dce$cdsclerk RELATED INFORMATION Books: OSF DCE Administration Guide 3 cdsd NAME cdsd - Restarts the CDS server SYNOPSIS cdsd [-a] [-D] [-l principal] [-w route] ARGUMENTS -a Creates a new namespace if there is not an existing namespace. This flag is meaningful only when the cell is first configured (that is, the initial creation of the namespace). -D For debugging use only. -l principal Locksmith mode. Allows the principal specified to have full access to all information stored with this server. -w route Routes serviceability messages. DESCRIPTION The cdsd command restarts the CDS server. This command starts the CDS server process automatically whenever the host system is rebooted. Privilege Required Your UIC must be DCE$SERVER. NOTES This command is ordinarily executed by the CDS startup script on the system where the CDS server is running. You should use this command interactively only if you want to do diagnostic work on the host system. EXAMPLE To restart a server, follow these steps: 1. Log in to the server system and set your UIC to DCE$SERVER. 2. Log into DCE as the machine principal of the local host. Enter the principal name in the format hosts/hostname/self as shown in the following example command for a host named mystic whose password is smith: $ dce_login hosts/mystic/self smith 3. Enter the following command to see if the dced process is already running: $ show system If the dced process appears on the list of active processes, proceed to step 4. If the dced process does not appear on the list of active processes, enter the following command to start the process: $ run sys$system:dce$dced 4. Enter the following command to see if the cdsadv process is already running: $ show system If the cdsadv process appears on the list of active processes, proceed to step 5. If the cdsadv process does not appear on the list of active processes, enter the following command to start the process: $ run sys$system:dce$cdsadver 5. Enter the following command to restart the server: $ run sys$system:dce$cdsd When the server process starts, it starts all clearinghouses on the system. RELATED INFORMATION Books: OSF DCE Administration Guide 3 gdad NAME gdad - Starts the GDA daemon SYNOPSIS gdad [-D] [-w route] OPTIONS -D For debugging use only. -w route Routes serviceability messages. DESCRIPTION The gdad command starts the GDA daemon. The Global Directory Agent (GDA) enables intercell communication, serving as a connection to other cells through the global naming environment. Privilege Required You must log in as superuser (root). NOTES Use this command only when troubleshooting. EXAMPLE To start the gdad process, follow these steps: 1. Make sure that a CDS server is already running somewhere within the cell. 2. Log in to the system and set your UIC to DCE$SERVER. 3. Log in to DCE as the machine principal of the local host. Enter the principal name in the format /hosts/hostname/self as shown in the following example command for a host named orion whose password is smith. $ dce_login hosts/orion/self smith 4. Enter the following command to see if the dced process is already running: $ show system If the dced process appears on the list of active processes, proceed to step 5. If the dced process does not appear on the list of active processes, enter the following command to start the process: $ run sys$system:dce$dced 5. Enter the following command to start the cdsadv process: $ run sys$system:dce$cdsadver 6. Enter the following command to start the gdad process: $ run sys$system:dce$gdad To stop the GDA, enter the following command: $ stop/id= where pid is the process identifier of the gdad process. RELATED INFORMATION Books: OSF DCE Administration Guide 3 nsedit NAME nsedit - Starts the CDS Browser/Editor utility on the local system SYNOPSIS nsedit DESCRIPTION The nsedit command starts the CDS Browser/Editor utility on the local system. This utility runs on workstations with windowing software based on the OSF/Motif graphical user interface. Using a mouse to manipulate pull-down menus, you can view and modify the directory structure of a namespace, view and modify child directories of a particular directory, view and modify the object entries and soft links in a directory, and set a filter to display only object entries of a particular class. (For users who do not have windowing software, similar functions are available with the control program.) When you use the CDS Browser/Editor, it sets the confidence level of clerk calls to low. Privilege Required None EXAMPLE The following command starts the CDS Browser/Editor utility on the local system: $ nsedit If the nsedit command is not currently defined, execute the following command file, and try again: $ @sys$manager:dce$define_required_commands 2 DCE_IDL NAME idl - Invokes the Interface Definition Language (IDL) compiler [required for developing distributed DCE applications] SYNOPSIS idl filename [argument] ... RELATED INFORMATION Books: OSF DCE Application Development Guide. 3 ARGUMENTS 4 -client -client file_type Determines which client files to generate. If you do not specify this argument, the compiler generates all client files. The file types are as follows: none Does not generate client files. stub Generates only a client stub file. aux Generates only a client auxiliary file. A client auxiliary file is generated only if the interface contains any out-of- line or self-pointing types. all Generates client stub and client auxiliary files. This is the default and is the same as not specifying the -client argument. 4 -server -server file_type Determines which server files to generate. If you do not specify this argument, the compiler generates all server files. The file types are as follows: none Does not generate server files. stub Generates only a server stub file. aux Generates only a server auxiliary file. A server auxiliary file is generated only if the interface contains any out-of- line, self-pointing, or pipe types. all Generates server stub and server auxiliary files. This is the default and is the same as not specifying the -server argument. 4 -standard -standard standard_type Allows you to specify portable or extended features of the OSF DCE. This option is useful when you perform builds. The standard_type argument specifies what IDL features to enable. If you do not specify this argument, the compiler generates warning messages for all features that are not available in the previous version of OSF DCE. You can specify one of the following values for the standard_type argument: portable Allows only the language features available in OSF DCE Version 1.0.2. dce_v10 Synonymous with the portable argument. dec_v10 Allows all language features supported by the standard dce_v10 argument, plus a set of HP extensions to its products based on OSF DCE Version 1.0. extended Allows all language features supported in the current version of the compiler. This is the default. dce_v11 Synonymous with the extended argument. The following example command line compiles the IDL interface test.idl and enables extended features of the OSF DCE: $ idl test.idl -standard extended 4 -cstub -cstub filename Specifies a pathname for the client stub file. When you give a filename, do not give a file extension; the idl compiler appends .c to the C source file and .o to the object file. If you do not use the -cstub argument, the idl compiler appends _cstub.c to the C source file and _cstub.o to the object file. If the -lang cxx option is used, the source file will have the .cxx extension. 4 -sstub -sstub filename Specifies a pathname for the server stub file. When you give a filename, do not give a file extension; the idl compiler appends .c to the C source file and .o to the object file. If you do not use the -sstub argument, the idl compiler appends _sstub.c to the C source file and _sstub.o to the object file. If the -lang cxx option is used, the source file will have the .cxx extension. 4 -caux -caux filename Specifies a pathname for the client auxiliary file. When you give a filename, do not give a file extension; the idl compiler appends .c to the C source file and .o to the object file. If you do not use the -caux argument, the idl compiler appends _caux.c to the C source file and _caux.o to the object file. If the -lang cxx option is used, the source file will have the .cxx extension. 4 -saux -saux filename Specifies a pathname for the server auxiliary file. When you give a filename, do not give a file extension; the idl compiler appends .c to the C source file and .o to the object file. If you do not use the -caux argument, the idl compiler appends _saux.c to the C source file and _saux.o to the object file. If the -lang cxx option is used, the source file will have the .cxx extension. 4 -header -header header_file Allows you to specify a name for the generated header file. By default the compiler takes the basename of the IDL file and appends the .h extension to it. 4 -out -out directory Places the output files in the directory you specify. By default the compiler places the output files in the current working directory. 4 -Idirectory -Idirectory Specifies a directory name that contains imported interface definition files. You can specify more than one directory by specifying additional -Idirectory arguments on the command line. The compiler searches the directories in the order you list them. If a file is present in more than one directory, the compiler takes the first occurrence of the file. The default behavior of the compiler is to first search the current directory, then all directories you specify, then the system IDL directory. The directory you specify is also passed to the C preprocessor and the C compiler. 4 -no_def_idir -no_def_idir Specifies that the compiler search only the current directory for imported files. When you use this with -Idirectory, the compiler searches only the directories you list, not the current directory, and not the system IDL directory. 4 -no_mepv -no_mepv Causes the compiler to not generate a manager entry point vector (EPV) in the server stub. Use this argument if the manager code and IDL file do not use the same operation names. If you specify this argument you must provide an EPV within the manager code that can be used when the interface is registered with the RPC server runtime. The name of the type that you construct an EPV with is if_name_vmajor-version_minor-version_epv_t where if_name is the interface name. It is not necessary to use this argument if the operation names in the manager code and IDL file are the same. In this case, the compiler generates a manager EPV in the server stub using the names of the operations in the IDL file. (For information on registering the server, see the rpc_intro and rpc_server_register_if reference pages. See the OSF DCE Application Development Guide.) 4 -cepv -cepv Generates local routines in the client stub file (filename_cstub.c) and defines a Client Entry Point Vector (CEPV) of the name if_name_vmajor-version_minor-version_c_epv where if_name is the interface name. The CEPV contains the addresses of the local routines. The client code must call the routines indirectly by using the addresses in the CEPV; otherwise, the stub routines in the client stub file must have the same names as the operations in the IDL file. (For information on registering the server, see the rpc_intro and rpc_server_register_if reference pages. See the OSF DCE Application Development Guide.) 4 -cpp_cmd -cpp_cmd 'c_preprocessor_command_line' Allows you to specify a C preprocessor other than the default. The compiler invokes the C preprocessor found in that command line. The output of the C preprocessor is an expanded version of the input file(s) containing replacement text for any preprocessor directives (for example, the #include preprocessor directive). 4 -cpp_opt -cpp_opt 'command_options' Specifies additional options to be passed to the C preprocessor. You can add options to the command line used to invoke the C preprocessor independent of the -cpp_cmd argument. The IDL compiler concatenates the -cpp_cmd, -cpp_opt, -D, -U, -I arguments and the source filename into a command used to invoke the C preprocessor. The compiler repeats this process for each Attribute Configuration File (ACF) and IDL file. 4 -no_cpp -no_cpp Does not invoke the C preprocessor. Note that the C preprocessor must be run on files that contain preprocessor directives (such as #include) in the interface definition. 4 -cc_cmd -cc_cmd 'command_line' Invokes the C compiler and compiler options you specify in the 'command_line' argument rather than the default C compiler and compiler options. When used with the -lang cxx option, the -cc_cmd option specifies the C++ compiler. 4 -cc_opt -cc_opt 'command_options' Specifies additional options to be passed to the C compiler. You can add options to the command line used to invoke the C compiler independent of the -cc_cmd argument. The IDL compiler concatenates the -cc_cmd, -cc_opt, -I arguments and the source filename into a command that invokes the C compiler. This procedure is done for each generated stub or auxiliary file. When used with the -lang cxx option, the -cc_opt option specifies the C++ compiler options. 4 -Dname -Dname[=definition] Defines a symbol name and an optional value to be passed to the C preprocessor. You can use this method of defining a symbol instead of using #define in the source code. You can use more than one -Dname argument on the command line. This argument has no effect if you use the -no_cpp argument. 4 -Uname -Uname Removes (undefines) any initial definition of a symbol name as defined by -Dname. You can use this method to remove a symbol name instead of using #undef in the source code. You can use more than one -Uname argument on the command line. This argument has no effect if you use the -no_cpp argument. If you define and undefine a name on the same command line, undefining takes precedence. 4 -space_opt -space_opt Generates code for the marshalling and unmarshalling of data that is optimized for space, rather than speed. 4 -syntax_only -syntax_only Checks only the syntax of the IDL file, but does not generate any output files. 4 -keep -keep file_types Specifies which files to retain. To produce the object modules, the IDL compiler first creates C source modules, then invokes the target C compiler to produce object modules, and finally, deletes the C source modules. If you do not use -keep, only the object modules are saved. The file types are as follows: none Does not save the C source or the object modules. Does not invoke the C compiler. c_source Saves only the C source modules. Does not invoke the C compiler. object Saves only the object modules. all Saves both the C source and the object modules. 4 -bug -bug n -no_bug n Retains (-bug) or does not retain (-no_bug) a specified bug from earlier IDL compiler versions. (This in an NCS compatibility argument and is not supported in OSF DCE Version 1.1). 4 -stdin -stdin Takes the standard output of a previous utility as the input to the idl command. For example: $ pipe type my_filename.idl | idl -stdin 4 -version -version Displays the current version of the IDL compiler. 4 -v -v Prints informational messages (verbose mode) on the screen while the compiler is running. 4 -no_warn -no_warn Suppresses compiler warning messages. 4 -confirm -confirm Displays all the idl command arguments you chose, but does not compile the source IDL file. If you use this with the -v argument, informational messages about how the compiler behaves if you do not use -confirm are displayed but no corresponding actions are performed. 4 -template_client -template_client filename Requests that the IDL compiler generate a C source file containing a template implementation of each routine that must appear in the client application to use the specified IDL interface. If you do not specify an extension for filename, the compiler assigns the file extension .c. 4 -template_manager -template_manager filename Requests that the IDL compiler generate a C source file containing a template implementation of each routine and operation that must appear in the manager module of the server side of an application to use the specified IDL interface. If you do not specify an extension for filename, the compiler assigns the file extension .c. 4 -trace -trace value Enables event logging. You can specify one of the following values for the value argument: all Log all events. none Disable all previously specified trace options. calls Log events relating to start and end of all RPC calls. context Log events relating to context handle creation, deletion, and rundown. errors Log errors. misc Log all miscellaneous events. log_manager Enable command interface support which allows modification at runtime of event logging options. 4 -lang -lang {c, cxx, fortran} Allows you to select a programming language. If you are generating stubs and include files for application code written in C++, you must specify cxx as the language of choice when you compile the application's IDL file. When appropriate, you can extend the class hierarchy and derive other classes from this one, to implement some or all interface operations. The C++ compiler gives a warning if any functions in the interface class have not been implemented. Avoid overwriting the manager class header file by using the -no_cxxmgr argument in conjunction with the -lang cxx argument. If you are generating stubs and include files for application code written in FORTRAN, you must specify FORTRAN as the language of choice when you compile the application's IDL file. If you do not specify -lang fortran or -lang cxx, the default value is the C programming language or -lang c. 4 -no_cxxmgr -no_cxxmgr Prevents the compiler from overwriting the manager class header file. Use this argument in conjunction with the -lang cxx argument if you implement application-specific C++ code in the manager class header file. 3 DESCRIPTION The idl command invokes the IDL compiler to convert an interface definition, written in IDL, into output files. The output files include a header file, server stub file, client stub file, and auxiliary files. The compiler constructs the names of the output files by keeping the basename of the interface definition source file but replacing the filename extension with the new extension (or suffix and extension) appropriate to the newly generated type of output file. For example, math.idl could produce math_sstub.c or math_sstub.o for the server stub. The idl command accepts the following input: + An interface definition filename. + Arguments to indicate either special actions to be performed by the compiler, or special properties of the input or output files. The IDL compiler searches through directories for any related ACF. For example, if you compile a file named source.idl, the compiler automatically searches for a file named source.acf. The compiler also searches for any imported IDL file (and its related ACF). The compiler searches for these files using the following order: 1. The current working directory. The compiler always searches this directory unless you specify the -no_def_idir and -Idirectory arguments together. 2. Any imported directory. The compiler searches each directory you are specifying in the -Idirectory argument. 3. The system IDL directory. The compiler automatically imports nbase.idl, which resides in the system IDL directory. The compiler always searches this directory unless you specify the -no_def_idir argument. 4. The directory specified in the source filename. If you explicitly specify a directory in the source IDL pathname, then that directory is searched for the corresponding ACF. For example, $ idl usera:[my_dir]my_source.idl causes the IDL compiler to look for usera:[my_dir]my_source.acf if my_source.acf is not found in the directories in 1,2 and 3. Note that this directory is not searched for any imported IDL file or its corresponding ACF. Restrictions The following filenames are reserved by the IDL compiler. Naming an IDL file with one of these names may result in unexpected behavior. iovector.idl lbase.idl nbase.idl ncastat.idl ndrold.idl rpc.idl rpcbase.idl rpcpvt.idl rpcsts.idl rpctypes.idl twr.idl uuid.idl 3 CAUTIONS The IDL compiler generates ANSI C code. It also supports C compilers that are not fully ANSI compliant although a warning message may occur during compilation of the stubs by the C compiler. A C compiler that is not fully ANSI compliant may generate the following warning messages: + warning: & before array or function: ignored + warning: enumeration type clash, operator = 3 FILES SYS$SYSTEM:DCE$IDL.EXE IDL Compiler SYS$COMMON:[DCE$LIBRARY] System IDL directory for imported files SYS$COMMON:[DCE$LIBRARY]NBASE.IDL Predefined IDL types SYS$COMMON:[DCE$LIBRARY]file.ext All .idl or .h files that are part of DCE RPC 3 EXAMPLES 1. Invoke the IDL compiler to compile the interface definition file test.idl and keep the generated C source modules. Only server files are generated. The server stub default filename is overridden by creating a file named test_ss.c for the server stub module. $ idl test.idl -keep c_source -client none -sstub test_ss.c 2. Invoke the IDL compiler to compile the interface definition file test.idl, but do not run the C preprocessor. The manager entry point vector is not defined in the generated server stub module. The IDL compiler searches the parent directory of the current directory for any IDL files that test.idl could import. The generated output files are located in the output subdirectory under the current directory. $ idl test.idl -no_cpp -no_mepv -I.. -out [.output] 3 DCL_Command_Interface The following is the DCL syntax for the IDL compiler. Except where noted, IDL DCL commands are equivalent to the IDL universal command syntax documented in the idl section of the OSF DCE Application Development Reference. See the Reference documentation for a complete description of the universal command syntax interface to the IDL compiler. NAME IDL - Invokes the Interface Definition Language (IDL) Compiler SYNOPSIS IDL file-spec [qualifier]... 4 QUALIFIERS /CLIENT_FILES /CLIENT_FILES [=(option[,...])] /NOCLIENT_FILES Specify one or more of the following options. ALL (default) [NO]AUXILIARY [=filename] NONE [NO]STUB [=filename] This qualifier is equivalent to the -client argument in the universal syntax. /SERVER_FILES /SERVER_FILES [=(option[,...])] /NOSERVER_FILES Specify one or more of the following options: ALL (default) [NO]AUXILIARY [=filename] NONE [NO]STUB [=filename] This qualifier is equivalent to the -server argument in the universal syntax. /STANDARD /STANDARD [=[NO]PORTABLE | DCE_V10 | DEC_V10 | EXTENDED ] /STANDARD=PORTABLE (default) This qualifier is equivalent to the -standard[standard_type] argument in the universal syntax. This universal syntax argument is documented in the section of the HP DCE Product Guide that describes additional IDL command options. /HEADER_FILE /HEADER_FILE = filename /HEADER_FILE=file_spec.H (default) This qualifier is equivalent to the -header header_file argument in the universal syntax. /OUTPUT_DIRECTORY /OUTPUT_DIRECTORY [=directory] /NOOUTPUT_DIRECTORY (default) This qualifier is equivalent to the -out directory argument in the universal syntax. /INCLUDE_DIRECTORY /INCLUDE_DIRECTORY [=(pathname [,...])] (default) /NOINCLUDE_DIRECTORY These qualifiers are equivalent to the -Idirectory and -no_def_idir arguments in the universal syntax. /ENTRY_POINT_VECTOR /ENTRY_POINT_VECTOR [=(option[,...])] /NOENTRY_POINT_VECTOR /ENTRY_POINT_VECTOR=(NOCLIENT, MANAGER) (default) Specify one or more of the following options: ALL [NO]CLIENT [NO]MANAGER NONE This qualifier provides a function similar to those of the -cepv and -no_mepv arguments in the universal syntax. The /ENTRY_POINT_VECTOR command qualifier controls generation of the client and manager entry point vectors through the keywords CLIENT and MANAGER. In the universal command syntax, two separate idl options (-cepv and -no_mepv) control generation of the client and manager entry point vectors. The following example universal command syntax generates both client and server entry point vectors: $ idl fpe_server.idl -cepv The equivalent DCL command is as follows: $ idl fpe-server.idl /ENTRY_POINT_VECTOR=CLIENT,MANAGER If one or more options are specified, the DCL syntax requires you to specify all required options. Options that are not listed are not enabled. /PREPROCESS /PREPROCESS /NOPREPROCESS (default) These qualifiers are equivalent to the -cpp_cmd 'c_preprocessor_command_line' and -no_cpp arguments in the universal syntax. /CC_COMMAND /CC_COMMAND [=command-line] /NOCC_COMMAND /CC_COMMAND="CC/G_FLOAT/STANDARD=NOPORTABLE" (default) This qualifier is equivalent to the -cc_cmd 'command_line' argument in the universal syntax. /CC_QUALIFIERS /CC_QUALIFIERS [="command-qualifiers"] /NOCC_QUALIFIERS (default) This qualifier is equivalent to the -cc_opt 'command_options' argument in the universal syntax. /DEFINE /DEFINE [=(identifier[=definition][,...])] /NODEFINE (default) This qualifier is equivalent to the -Dname[=definition] argument in the universal syntax. /UNDEFINE /UNDEFINE [=(identifier[,...])] /NOUNDEFINE (default) This qualifier is equivalent to the -Uname argument in the universal syntax. /OPTIMIZE /OPTIMIZE [=({SPEED | SPACE })] /OPTIMIZE = SPEED (default) This qualifier is equivalent to the -space_opt argument in the universal syntax. /SYNTAX_ONLY /SYNTAX_ONLY /NOSYNTAX_ONLY (default) This qualifier is equivalent to the -syntax_only argument in the universal syntax. /KEEP /KEEP [=option] /NOKEEP Specify one of the following options: ALL C_SOURCE NONE (equivalent to /NOKEEP) OBJECT (default) This qualifier is equivalent to the -keep file_types argument in the universal syntax. /REPAIR /REPAIR [=(option[,...])] /NOREPAIR Specify one of the following options: [NO]BOOLEAN_CONSTANTS [NO]EXTRA_PAD_BYTES [NO]MISSING_PAD_BYTES ALL (default) NONE These qualifiers are equivalent to the -bug n and -no_bug n arguments in the universal syntax. The values [NO]BOOLEAN_CONSTANTS, [NO]EXTRA_PAD_BYTES, and [NO]MISSING_PAD_BYTES correspond to -bug 1, -bug 2, and -bug 3 respectively in the universal syntax. /VERSION /VERSION /NOVERSION (default) This qualifier is equivalent to the -version argument in the universal syntax. /LOG /LOG /NOLOG (default) This qualifier is equivalent to the -v argument in the universal syntax. /WARNINGS /WARNINGS (default) /NOWARNINGS This qualifier is equivalent to the -no_warn argument in the universal syntax. /VERIFY /VERIFY /NOVERIFY (default) This qualifier is equivalent to the -confirm argument in the universal syntax. /TRACE /TRACE [=(option[,...)] /NOTRACE Specify one or more of the following options: [NO]LOG_MANAGER EVENTS=({ALL|CALLS|CONTEXT_HANDLES|ERRORS|NONE|MISCELLANEOUS}[,...]) /NOTRACE (default) This qualifier is equivalent to the -trace value argument in the universal syntax, which is documented in the HP DCE Product Guide. /LANGUAGE /LANGUAGE [={CC | CXX | FORTRAN}] /LANGUAGE=CC (default) This qualifier is equivalent to the -lang argument in the universal syntax. /DIAGNOSTICS /DIAGNOSTICS [=filename] /NODIAGNOSTICS (default) Specifies that a diagnostic file listing the errors reported by a compilation should be generated for LSE. If you do not specify a filename, the compiler uses the basename of the IDL file and appends the .DIA extension to it. 3 Event_Logger NAME idl -trace - Starts the RPC Event Logger The idl -trace command enables event logging for an application interface. The event logger records information about the following types of events: interface calls, context handles, errors, event logging itself, and a miscellaneous group of events. SYNOPSIS idl file-spec -trace {arguments} ARGUMENTS all Log all events none Disable all previously specified trace options calls Log events relating to start and end of all RPC calls context Log events relating to context handle creation, deletion, and rundown errors Log errors misc Log all miscellaneous events log_manager Enable command interface support which allows modification at runtime of event logging options RELATED_INFORMATION "HP DCE for OpenVMS Alpha and OpenVMS I64 Product Guide" 4 DESCRIPTION The RPC Event Logger records event information in an event log, which can be directed to the terminal screen or to a file. Use the -trace universal syntax (or /TRACE DCL interface) to enable and modify event logging prior to linking the interface. After linking the interface, you can use the Log Manager command line interface (rpclm) or an OpenVMS symbol (RPC_LOG_FILE) to modify event logging options at runtime. The DCL interface to the event logger has the following syntax: /[NO]TRACE =(option[,...]) Specify one or more of the following options: [NO]LOG_MANAGER EVENTS=({ALL|NONE|ERRORS|CALLS|CONTEXT_HANDLES|MISCELLANEOUS}[,...]) RPC events are as follows: activate A thread was assigned to process an RPC call on a server, and the server stub has started processing input arguments. The Event Data field of the event log contains the string binding of the client application making the call. await_reply The transmission of input arguments in a call from a client application to a server has completed. The event is generated by the client stub. The client application is waiting for output arguments from the server. call_end A call from a client application is complete and the client stub is returning to the caller. call_failure A client stub terminated abnormally because either an exception occurred or due to a failing status. The Event Data field of the event log contains the error text associated with the exception or RPC status code. call_start A client application attempted to make a call to a server. The event is generated by the stub within the client application. The Event Data field of the event log displays the string binding of the server being contacted. client_ctx_created A client application has allocated a context handle on a particular server. The Event Data field of the event log contains the following information about this event: * The address representing the context handle in the client address space (an opaque pointer) * The UUID which can be used to identify the corresponding context handle on the server * The string binding of the server on which the actual context resides client_ctx_deleted The client application representation of a context handle is being deleted to reflect the deletion of the context handle on the server. The Event Data field of the event log contains the following information about this event: * The address representing the context handle in the client address space (an opaque pointer) * The UUID which can be used to identify the corresponding context handle on the server * The string binding of the server on which the actual context resided client_ctx_destroyed A client application has destroyed the client representation of a context handle through the rpc_ss_destroy_client_context routine. The Event Data field of the event log contains the following information about this event: * The address representing the context handle in the client address space (an opaque pointer) * The UUID which can be used to identify the corresponding context handle on the server * The string binding of the server on which the actual context resided context_created A new context handle was created on a server and returned from the application manager routine. The Event Data field of the event log contains both the application value of the context handle and the UUID assigned to represent this context handle. context_deleted A context handle on a server has been deleted by the application manager routine. The Event Data field of the event log contains both the application value of the context handle and the UUID assigned to represent this context handle. context_modified A context handle on a server was returned from the application manager routine with a value that is different from its previous value. The Event Data field of the event log contains both the application value of the context handle and the UUID assigned to represent this context handle. context_rundown A context handle on a server was freed by the context rundown procedure. The Event Data field of the event log contains both the application value of the context handle and the UUID assigned to represent this context handle. exception An exception was detected in the server stub, and the exception caused the call to terminate. The Event Data field of the event log contains a text description of the exception. internal_error A failure occurred in the support routines that manage the event logger. Check the Event Data field of the event log for a description of the cause of the event. If the error does not seem to indicate a transient network problem or an environmental failure, report the failure in a Software Performance Report (SPR). listening The RPC Log Manager has started to listen for rpclm commands. The listening event is generated by the portion of the RPC Log Manager built into your application by the RPC run time when you specify the -trace log_manager option on your IDL compilation. The RPC Log Manager services the requests generated by the rpclm command. You use one of the string bindings from a listening event to invoke the rpclm command interface. log_events Event logging was modified through the Log Manager command interface rpclm. The Event Data field of the event log contains the new set of events being logged. log_file Event logging was modified through the Log Manager command interface rpclm. The Event Data field of the event log contains the new file name for the event log. If no file name is displayed, events are being logged to the screen. log_start A new event log was created or event logging was resumed after being suspended by a user command to the Log Manager command interface rpclm. The Event Data field in the event log contains a list of event types being logged. log_stop Event logging was stopped through the Log Manager interface rpclm. manager_call The server stub is about to call the application manager routine. manager_return Control has just returned from the application manager routine to the server stub. rebind A call from a client application to a server failed. The Event Data field in the event log shows the reason for the failure to contact the server. The event is generated by the stub within the client application. The call failed on an auto_handle operation and the client is attempting to rebind to the next server. receive Following the transmission of input arguments from a client application call to a server, the client received a reply and started processing output arguments. receive_fault The client received a fault indicating a failure on the server. The Event Data field of the event log contains the RPC status that identifies the failure. All failures have fault codes which you can find in the file ncastat.idl. If the fault code in the ncastat.idl file is too general (such as "unspecified fault"), examine the server event log for precise failure information. status_fail A failure status was encountered in the server stub. The Event Data field of the event log describes the failure. terminate The server thread has completed processing the call and has terminated. transmit_fault The server runtime is sending fault information to the client application. The Event Data field of the event log indicates the name of the fault being sent. The fault information in this field is listed in the ncastat.idl file. The fault information in this field may be less descriptive than the information logged about the actual error. (See the exception or status_fail events in the event log to obtain precise failure information.) 4 EXAMPLES Compile the binopwk interface and enable event logging for all events: $ idl binopwk.idl -trace all Compile the binopwk interface and enable event logging for errors: $ idl binopwk.idl -trace errors Compile the binopwk interface, enabling event logging for all events as well as enabling the log manager interface: $ idl binopwk.idl -trace all -trace log_manager The event logger universal interface has the following DCL command equivalents: -trace all /TRACE=EVENTS=ALL -trace log_manager /TRACE=LOG_MANAGER -trace all -trace log_manager /TRACE=(LOG_MANAGER,EVENTS=ALL) -trace errors -trace calls /TRACE=EVENTS=(ERRORS,CALLS) 3 rpclm NAME rpclm - Starts the command line interface to the RPC Event Logger Log Manager SYNOPSIS rpclm "listening event string binding" ARGUMENTS inquire Inquire about the currently logged events and determine the name of the active log file. log Specify additional events to log: all, none, calls, context, errors, or misc. unlog Disable logging of the specified event types: all, none, calls, context, errors, or misc. file Change the output device or file to which events are logged. quit Terminate the rpclm session. help Display a description of the rpclm command interface commands. 4 DESCRIPTION The RPC Event Logger records information in an event log about application execution. After enabling the Log Manager when you compile the interface, you can use the Log Manager command line options to modify event logging parameters at runtime. Follow these steps to enable the RPC Log Manager: 1. Use the -trace log_manager option at IDL compilation time. 2. Create the RPC_LOG_FILE symbol and assign it to a file name or to screen output. 3. Execute the client or server process, or both. 4. When the first call is made to an interface compiled with the -trace option, a listening event will be generated into the event log. Invoke the rpclm command interface by specifying the string binding from the listening event. EXAMPLES To enable the Log Manager, use the following syntax: $ idl file-name.idl -trace log_manager To invoke the rpclm command interface, specify the string binding from a listening event, as in the following example: $ rpclm ncacn_ip_tcp:16.31.48.144[3820] RELATED INFORMATION "HP DCE for OpenVMS Alpha and OpenVMS I64 Product Guide" 2 DCE$SETUP.COM NAME dce$setup.com - Configures and starts up DCE DESCRIPTION The dce$setup.com command file invokes an enhanced configuration utility to configure and start DCE services. The configuration utility displays a menu that allows you to perform the following operations: + Configure DCE services (config) + Show DCE configuration and active daemons (show) + Terminate all active DCE daemons (stop) + Start all DCE daemons (start) + Terminate and restart all DCE daemons (restart) + Terminate all active DCE daemons and remove all temporary local DCE databases (clean) + Terminate all active DCE daemons and remove all permanent local DCE databases (clobber) + Run the Configuration Verification Program (test) PERMISSIONS REQUIRED You must have privileges to run the dce$setup.com command file for most operations except "show". See the DCE for OpenVMS Installation and Configuration Guide and the DCE for OpenVMS Product Guide for more information about dce$setup.com.