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.
1 – KIT_DESCRIPTIONS
1.1 – 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)
1.2 – 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
1.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.
1.4 – 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.
2.1 – 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.
3 – 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.1 – 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.
3.1.1 – dce_attr_sch_bind
NAME
dce_attr_sch_bind - Return an opaque handle to a schema object
SYNOPSIS
#include <dce/dce_attr_base.h>
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
3.1.2 – 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 <dce/dce_attr_base.h>
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
3.1.3 – 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 <dce/dce_attr_base.h>
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
3.1.4 – dce_attr_sch_update_entry
NAME
dce_attr_sch_update_entry - Update a schema entry
SYNOPSIS
#include <dce/dce_attr_sch.h>
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
3.1.5 – dce_attr_sch_delete_entry
NAME
dce_attr_sch_delete_entry - Delete a schema entry
SYNOPSIS
#include <dce/dce_attr_sch.h>
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
3.1.6 – dce_attr_sch_scan
NAME
dce_attr_sch_scan - Read a specified number of schema entries
SYNOPSIS
#include <dce/dce_attr_base.h>
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
3.1.7 – 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 <dce/dce_attr_base.h>
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
3.1.8 – 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 <dce/dce_attr_sch.h>
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
3.1.9 – 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 <dce/dce_attr_base.h>
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
3.1.10 – 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 <dce/dce_attr_base.h>
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
3.1.11 – dce_attr_sch_lookup_by_id
NAME
dce_attr_sch_lookup_by_id - Read a schema entry identified by UUID
SYNOPSIS
#include <dce/dce_attr_base.h>
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
3.1.12 – dce_attr_sch_lookup_by_name
NAME
dce_attr_sch_lookup_by_name - Read a schema entry identified by name
SYNOPSIS
#include <dce/dce_attr_base.h>
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
3.1.13 – 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 <dce/dce_attr_base.h>
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.2 – 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:
3.2.1 – dce_cf_binding_entry_from_host
NAME
dce_cf_binding_entry_from_host - Returns the host binding entry
name
SYNOPSIS
#include <dce/dce_cf.h>
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
3.2.2 – dce_cf_dced_entry_from_host
NAME
dce_cf_dced_entry_from_host - Returns the dced entry name on a host
SYNOPSIS
#include <dce/dce_cf.h>
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.
3.2.3 – dce_cf_find_name_by_key
NAME
dce_cf_find_name_by_key - Returns a string tagged by a character
string key
SYNOPSIS
#include <dce/dce_cf.h>
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
<dce_cf.h>.
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.
3.2.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 <dce/dce_cf.h>
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.
3.2.5 – dce_cf_get_cell_aliases
NAME
dce_cf_get_cell_aliases - Returns a list of aliases for the local
cell
SYNOPSIS
#include <dce/dce_cf.h>
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.
3.2.6 – dce_cf_get_cell_name
NAME
dce_cf_get_cell_name - Returns the primary name for the local
cell
SYNOPSIS
#include <dce/dce_cf.h>
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.
3.2.7 – 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 <dce/dce_cf.h>
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.
3.2.8 – dce_cf_get_host_name
NAME
dce_cf_get_host_name - Returns the hostname relative to the local
cell root
SYNOPSIS
#include <dce/dce_cf.h>
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.
3.2.9 – dce_cf_prin_name_from_host
NAME
dce_cf_prin_name_from_host - Returns the host's principal name
SYNOPSIS
#include <dce/dce_cf.h>
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.
3.2.10 – dce_cf_profile_entry_from_host
NAME
dce_cf_profile_entry_from_host - Returns the host profile entry
SYNOPSIS
#include <dce/dce_cf.h>
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.
3.2.11 – 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 <dce/dce_cf.h>
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.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
3.3.1 – dce_db_close
NAME
dce_db_close - Closes an open backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
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
3.3.2 – dce_db_delete
NAME
dce_db_delete - Deletes an item from a backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
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
3.3.3 – dce_db_delete_by_name
NAME
dce_db_delete_by_name - Deletes an item from a string-indexed
backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
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
3.3.4 – dce_db_delete_by_uuid
NAME
dce_db_delete_by_uuid - Deletes an item from a UUID-indexed
backing-store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
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
3.3.5 – dce_db_fetch
NAME
dce_db_fetch - Retrieves data from a backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
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
3.3.6 – dce_db_fetch_by_name
NAME
dce_db_fetch_by_name - Retrieves data from a string-indexed
backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
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
3.3.7 – dce_db_fetch_by_uuid
NAME
dce_db_fetch_by_uuid - Retrieves data from a UUID-indexed backing
store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
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
3.3.8 – dce_db_free
NAME
dce_db_free - Releases the data supplied from a backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
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
3.3.9 – dce_db_header_fetch
NAME
dce_db_header_fetch - Retrieves the header from a backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
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
3.3.10 – dce_db_inq_count
NAME
dce_db_inq_count - Returns the number of items in a backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
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
3.3.11 – dce_db_iter_done
NAME
dce_db_iter_done - Frees the state associated with iteration
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
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
3.3.12 – dce_db_iter_next
NAME
dce_db_iter_next - During iteration, returns the next key from
a backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
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
3.3.13 – 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 <dce/dce.h>
#include <dce/dbif.h>
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
3.3.14 – 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 <dce/dce.h>
#include <dce/dbif.h>
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
3.3.15 – dce_db_iter_start
NAME
dce_db_iter_start - Prepares a backing store for iteration
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
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
3.3.16 – dce_db_lock
NAME
dce_db_lock - Applies an advisory lock on a backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
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
3.3.17 – dce_db_open
NAME
dce_db_open - Opens an existing backing store or creates a new one
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
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
3.3.18 – dce_db_std_header_init
NAME
dce_db_std_header_init - Initializes a standard backing store header
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
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
3.3.19 – dce_db_store
NAME
dce_db_store - Stores data into a backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
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
3.3.20 – dce_db_store_by_name
NAME
dce_db_store_by_name - Stores data into a string-indexed backing
store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
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
3.3.21 – dce_db_store_by_uuid
NAME
dce_db_store_by_uuid - Stores data into a UUID-indexed backing store
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
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
3.3.22 – dce_db_unlock
NAME
dce_db_unlock - Releases the backing store lock
SYNOPSIS
#include <dce/dce.h>
#include <dce/dbif.h>
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.4 – 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
3.4.1 – dce_error_inq_text
NAME
dce_error_inq_text - Retrieves message text associated with a DCE
error code
SYNOPSIS
#include <dce/dce_error.h>
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 );
}
3.4.2 – dce_msg_cat_close
NAME
dce_msg_cat_close - DCE message catalog close routine
SYNOPSIS
#include <dce/dce_msg.h>
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
3.4.3 – dce_msg_cat_get_msg
NAME
dce_msg_cat_get_msg - DCE message text retrieval routine
SYNOPSIS
#include <dce/dce_msg.h>
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
3.4.4 – dce_msg_cat_open
NAME
dce_msg_cat_open - DCE message catalog open routine
SYNOPSIS
#include <dce/dce_msg.h>
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
3.4.5 – dce_msg_define_msg_table
NAME
dce_msg_define_msg_table - Adds a message table to in-memory table
SYNOPSIS
#include <dce/dce_msg.h>
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 <dce/dce.h>
#include <dce/dce_msg.h>
#include <dce/dcesvcmsg.h>
#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 <dce/dce_msg.h>. 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
3.4.6 – dce_msg_get
NAME
dce_msg_get - Retrieves text of specified DCE message
SYNOPSIS
#include <dce/dce_msg.h>
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
3.4.7 – dce_msg_get_cat_msg
NAME
dce_msg_get_cat_msg - Opens message catalog and retrieves message
SYNOPSIS
#include <dce/dce_msg.h>
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
3.4.8 – dce_msg_get_default_msg
NAME
dce_msg_get_default_msg - Retrieves DCE message from in-memory tables
SYNOPSIS
#include <dce/dce_msg.h>
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 <dce/dce.h>
#include <dce/dce_msg.h>
#include <dce/dcesvcmsg.h>
#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
3.4.9 – dce_msg_get_msg
NAME
dce_msg_get_msg - Retrieve a DCE message from its ID
SYNOPSIS
#include <dce/dce_msg.h>
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
3.4.10 – dce_msg_translate_table
NAME
dce_msg_translate_table - Translates all in-memory messages in
a table
SYNOPSIS
#include <dce/dce_msg.h>
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 <dce/dce.h>
#include <dce/dce_msg.h>
#include <dce/dcesvcmsg.h>
#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
3.4.11 – dce_pgm_printf
NAME
dce_pgm_printf
dce_pgm_fprintf
dce_pgm_sprintf - Formatted DCE message output routines
SYNOPSIS
#include <dce/dce.h>
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
3.4.12 – dce_printf
NAME
dce_printf
dce_fprintf
dce_sprintf - Formatted DCE message output routines
SYNOPSIS
#include <dce/dce.h>
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.5 – 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
3.5.1 – dce_server_disable_service
NAME
dce_server_disable_service - Disables an individual service of a
server
SYNOPSIS
#include <dce/dced.h>
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
3.5.2 – dce_server_enable_service
NAME
dce_server_enable_service - Enables an individual service for a
server
SYNOPSIS
#include <dce/dced.h>
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
3.5.3 – dce_server_inq_attr
NAME
dce_server_inq_attr - Obtains from dced the value of an attribute
known to the server
SYNOPSIS
#include <dce/dced.h>
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
3.5.4 – dce_server_inq_server
NAME
dce_server_inq_server - Obtains the server configuration data dced
used to start the server
SYNOPSIS
#include <dce/dced.h>
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
3.5.5 – 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 <dce/dced.h>
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
3.5.6 – dce_server_register
NAME
dce_server_register - Registers a server with DCE
SYNOPSIS
#include <dce/dced.h>
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
3.5.7 – 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 <dce/dced.h>
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
3.5.8 – 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 <dce/dced.h>
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
3.5.9 – dce_server_unregister
NAME
dce_server_unregister - Unregisters a DCE server
SYNOPSIS
#include <dce/dced.h>
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
3.5.10 – 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 <dce/dced.h>
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.6 – 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
3.6.1 – dce_assert
NAME
dce_assert - Inserts program diagnostics
SYNOPSIS
#define DCE_ASSERT
#include <dce/assert.h>
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
3.6.2 – dce_svc_components
NAME
dce_svc_components - DCE serviceability routine that returns
registered component names
SYNOPSIS
#include <dce/dce.h>
#include <dce/svcremote.h>
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
3.6.3 – dce_svc_debug_routing
NAME
dce_svc_debug_routing - Specifies how debugging messages are routed
SYNOPSIS
#include <dce/dce.h>
#include <dce/svcremote.h>
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
3.6.4 – dce_svc_debug_set_levels
NAME
dce_svc_debug_set_levels - Sets the debugging level for a component
SYNOPSIS
#include <dce/dce.h>
#include <dce/svcremote.h>
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
3.6.5 – dce_svc_define_filter
NAME
dce_svc_define_filter - DCE serviceability filtering routines
SYNOPSIS
#include <stdarg.h>
#include <dce/dce.h>
#include <pthread.h>
#include <dce/svcfilter.h>
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
3.6.6 – dce_svc_filter
NAME
dce_svc_filter - Controls behavior of serviceability filter
SYNOPSIS
#include <dce/dce.h>
#include <dce/svcremote.h>
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
3.6.7 – dce_svc_log_close
NAME
dce_svc_log_close - Closes an open logfile
SYNOPSIS
#include <dce/dce.h>
#include <pthread.h>
#include <dce/svclog.h>
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
3.6.8 – dce_svc_log_get
NAME
dce_svc_log_get - Reads the next record from a binary logfile
SYNOPSIS
#include <dce/dce.h>
#include <pthread.h>
#include <dce/svclog.h>
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
3.6.9 – dce_svc_log_open
NAME
dce_svc_log_open - Opens binary log file
SYNOPSIS
#include <dce/dce.h>
#include <pthread.h>
#include <dce/svclog.h>
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
3.6.10 – dce_svc_log_rewind
NAME
dce_svc_log_rewind - Rewinds binary logfile to first record
SYNOPSIS
#include <dce/dce.h>
#include <pthread.h>
#include <dce/svclog.h>
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
3.6.11 – dce_svc_printf
NAME
dce_svc_printf - Generates a serviceability message
SYNOPSIS
#include <dce/dce.h>
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
3.6.12 – dce_svc_register
NAME
dce_svc_register - Registers a serviceability message table
SYNOPSIS
#include <dce/dce.h>
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
3.6.13 – dce_svc_routing
NAME
dce_svc_routing - Specifies routing of serviceability messages
SYNOPSIS
#include <dce/dce.h>
#include <dce/svcremote.h>
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
3.6.14 – dce_svc_set_progname
NAME
dce_svc_set_progname - Sets an application's program name
SYNOPSIS
#include <dce/dce.h>
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
3.6.15 – dce_svc_table
NAME
dce_svc_table - Returns a registered component's subcomponent table
SYNOPSIS
#include <dce/dce.h>
#include <dce/svcremote.h>
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 <dce/rpc.h>
#include <dce/service.h>
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
3.6.16 – dce_svc_unregister
NAME
dce_svc_unregister - Destroys a serviceability handle
SYNOPSIS
#include <dce/dce.h>
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.7 – 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
3.7.1 – DCE_SVC_DEBUG
NAME
DCE_SVC_DEBUG - Macro to output a serviceability debug message
SYNOPSIS
#include <dce/dce.h>
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
3.7.2 – DCE_SVC_DEBUG_ATLEAST
NAME
DCE_SVC_DEBUG_ATLEAST - Macro to test a component's serviceability
debug level
SYNOPSIS
#include <dce/dce.h>
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
3.7.3 – DCE_SVC_DEBUG_IS
NAME
DCE_SVC_DEBUG_IS - Macro to test a component's serviceability debug
level
SYNOPSIS
#include <dce/dce.h>
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
3.7.4 – DCE_SVC_DEFINE_HANDLE
NAME
DCE_SVC_DEFINE_HANDLE - Macro to create a serviceability handle
SYNOPSIS
#include <dce/dce.h>
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
3.7.5 – DCE_SVC_LOG
NAME
DCE_SVC_LOG - Macro to output a binary form of a serviceability
debug message
SYNOPSIS
#include <dce/dce.h>
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.8 – 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
3.8.1 – 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
3.8.1.1 – 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 <dce/dced.h>
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.
3.8.1.2 – 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 <dce/dced.h>
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.
3.8.1.3 – dced_binding_set_auth_info
NAME
dced_binding_set_auth_info - Sets authentication and authorization
information for a dced binding handle
SYNOPSIS
#include <dce/dced.h>
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.
3.8.1.4 – dced_binding_free
NAME
dced_binding_free - Releases the resources associated with a dced
binding handle
SYNOPSIS
#include <dce/dced.h>
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.
3.8.2 – 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
3.8.2.1 – 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 <dce/dced.h>
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.
3.8.2.2 – dced_entry_remove
NAME
dced_entry_remove - Removes a hostdata or keytab data entry from
a dced service's list of entries
SYNOPSIS
#include <dce/dced.h>
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.
3.8.2.3 – 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 <dce/dced.h>
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.
3.8.2.4 – dced_entry_get_next
NAME
dced_entry_get_next - Obtains one data entry from a list of entries
of a dced service
SYNOPSIS
#include <dce/dced.h>
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.
3.8.2.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 <dce/dced.h>
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.
3.8.2.6 – dced_list_get
NAME
dced_list_get - Returns the list of data entries maintained by a
dced service on a specific host
SYNOPSIS
#include <dce/dced.h>
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<entries.count; i++)
display(&entries); /* application specific */
dced_list_release( dced_bh, &entries, &status );
dced_binding_free( dced_bh, &status );
RELATED INFORMATION
Routines: dced_list_release
dced_initialize_cursor
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
3.8.2.7 – dced_list_release
NAME
dced_list_release - Releases the resources for a list of entries
of a dced service
SYNOPSIS
#include <dce/dced.h>
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.
3.8.2.8 – dced_inq_id
NAME
dced_inq_id - Obtains the entry UUID that dced associates with
a name
SYNOPSIS
#include <dce/dced.h>
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.
3.8.2.9 – dced_inq_name
NAME
dced_inq_name - Obtains the entry name that dced associates with
a UUID
SYNOPSIS
#include <dce/dced.h>
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.
3.8.3 – 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
3.8.3.1 – dced_object_read
NAME
dced_object_read - Reads a data item of a dced service on a
specific host
SYNOPSIS
#include <dce/dced.h>
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<entries.count; i++) {
dced_object_read( dced_bh,
&entries.list[i].id,
&data,
&status );
.
.
.
dced_objects_release( dced_bh, 1, data, &status );
}
.
.
.
RELATED INFORMATION
Routines: dced_objects_release
dced_objects_read_all
dced_hostdata_read
dced_keytab_initialize_cursor
dced_initialize_cursor
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
3.8.3.2 – dced_object_read_all
NAME
dced_object_read_all - Reads all the data for a service of the
DCE Host daemon (dced) on specific host
SYNOPSIS
#include <dce/dced.h>
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.
3.8.3.3 – dced_objects_release
NAME
dced_objects_release - Releases the resources allocated for data
read from a dced service
SYNOPSIS
#include <dce/dced.h>
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<entries.count; i++) {
dced_object_read( dced_bh,
&(entries.list[i].id),
&data,
&status );
display( host_service, 1, &data ); /* app. specific */
dced_objects_release( dced_bh, 1, data, &status );
.
.
.
RELATED INFORMATION
Routines: dced_object_read
dced_object_read_all
dced_hostdata_read
dced_binding_create
dced_binding_from_rpc_binding
Books: OSF DCE Application Development Guide.
3.8.4 – Host Data Management Routines
dced_hostdata_create
Creates a hostdata item and the associated entry
dced_hostdata_read Reads a hostdata item
dced_hostdata_write Replaces an existing hostdata item
dced_hostdata_delete
Deletes a hostdata item from a specific host and
removes the associated entry
3.8.4.1 – dced_hostdata_create
NAME
dced_hostdata_create - Creates a hostdata item and the associated
entry in dced on a specific host
SYNOPSIS
#include <dce/dced.h>
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.
3.8.4.2 – dced_hostdata_read
NAME
dced_hostdata_read - Reads a hostdata item maintained by dced
on a specific host
SYNOPSIS
#include <dce/dced.h>
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.
3.8.4.3 – dced_hostdata_write
NAME
dced_hostdata_write - Replaces an existing hostdata item
maintained by dced on a specific host
SYNOPSIS
#include <dce/dced.h>
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.
3.8.4.4 – dced_hostdata_delete
NAME
dced_hostdata_delete - Deletes a hostdata item from a specific
host and removes the associated entry
from dced
SYNOPSIS
#include <dce/dced.h>
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.
3.8.5 – 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
3.8.5.1 – dced_server_create
NAME
dced_server_create - Creates a DCE server's configuration data
for the host's dced
SYNOPSIS
#include <dce/dced.h>
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.
3.8.5.2 – dced_server_modify_attributes
NAME
dced_server_modify_attributes - Modifies attributes for a DCE
server's configuration data
SYNOPSIS
#include <dce/dced.h>
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
3.8.5.3 – dced_server_delete
NAME
dced_server_delete - Deletes a DCE server's configuration data
from dced
SYNOPSIS
#include <dce/dced.h>
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.
3.8.5.4 – dced_server_start
NAME
dced_server_start - Starts a DCE-configured server on a
specified host
SYNOPSIS
#include <dce/dced.h>
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.
3.8.6 – 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
3.8.6.1 – 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 <dce/dced.h>
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.
3.8.6.2 – dced_server_enable_if
NAME
dced_server_enable_if - Enables a service (rpc interface) of
a specific server on a specific host
SYNOPSIS
#include <dce/dced.h>
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.
3.8.6.3 – dced_server_stop
NAME
dced_server_stop - Stops a DCE-configured server running on a
specific host
SYNOPSIS
#include <dce/dced.h>
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.
3.8.7 – 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
3.8.7.1 – dced_secval_start
NAME
dced_secval_start - Starts the security validation service of
a specific host's dced
SYNOPSIS
#include <dce/dced.h>
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.
3.8.7.2 – dced_secval_validate
NAME
dced_secval_validate - Validates that the secd used by a
specific host is legitimate
SYNOPSIS
#include <dce/dced.h>
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.
3.8.7.3 – dced_secval_status
NAME
dced_secval_status - Indicates whether or not a specific host's
security validation service of dced is
running
SYNOPSIS
#include <dce/dced.h>
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.
3.8.7.4 – dced_secval_stop
NAME
dced_secval_stop - Stops the security validation service of
a specific host's dced
SYNOPSIS
#include <dce/dced.h>
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.
3.8.8 – 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
3.8.8.1 – 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 <dce/dced.h>
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.
3.8.8.2 – dced_keytab_delete
NAME
dced_keytab_delete - Deletes a key table file from a specific host
SYNOPSIS
#include <dce/dced.h>
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.
3.8.8.3 – 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 <dce/dced.h>
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.
3.8.8.4 – 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 <dce/dced.h>
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.
3.8.8.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 <dce/dced.h>
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.
3.8.8.6 – 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 <dce/dced.h>
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.
3.8.8.7 – 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 <dce/dced.h>
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.
3.8.8.8 – 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 <dce/dced.h>
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.
3.8.9 – 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.
4 – 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.
4.1 – 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
4.2 – dce_config
NAME The dce$setup.com command file replaces the dce_config command. See the dce$setup.com help for more information.
4.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
<error message>
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>
4.4 – 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.
4.5 – 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
5 – 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.
5.1 – 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
5.1.1 – 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.
5.1.2 – 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.
5.1.3 – 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.
5.1.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.
5.1.5 – 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.
5.1.6 – 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.
5.1.7 – 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.
5.1.8 – 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.
5.1.9 – Condition Variable Attributes Object Routines
pthread_condattr_destroy
Destroys a condition variable attributes
object.
pthread_condattr_init Initializes a condition variable attributes
object.
5.1.10 – 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.1.10.1 – 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.1.10.2 – 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.1.10.3 – 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.1.10.4 – 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.1.10.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.1.10.6 – 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.
5.2 – Application Routines
5.2.1 – 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 <pthread.h>
with the following include statement:
#include <pthread_exc.h>
The following example shows the syntax for handling exceptions:
TRY
try_block
[CATCH (exception_name)
handler_block]...
[CATCH_ALL
handler_block]
ENDTRY
5.2.2 – pthread_attr_create
NAME
pthread_attr_create - Creates a thread attributes object
SYNOPSIS
#include <pthread.h>
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
5.2.3 – pthread_attr_delete
NAME
pthread_attr_delete - Deletes a thread attributes object
SYNOPSIS
#include <pthread.h>
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
5.2.4 – pthread_attr_getinheritsched
NAME
pthread_attr_getinheritsched - Obtains the inherit
scheduling attribute
SYNOPSIS
#include <pthread.h>
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
5.2.5 – pthread_attr_getprio
NAME
pthread_attr_getprio - Obtains the scheduling priority attribute
SYNOPSIS
#include <pthread.h>
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
5.2.6 – pthread_attr_getsched
NAME
pthread_attr_getsched - Obtains the value of the scheduling
policy attribute
SYNOPSIS
#include <pthread.h>
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
5.2.7 – pthread_attr_getstacksize
NAME
pthread_attr_getstacksize - Obtains the value of the
stacksize attribute
SYNOPSIS
#include <pthread.h>
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
5.2.8 – pthread_attr_setinheritsched
NAME
pthread_attr_setinheritsched - Changes the inherit scheduling
attribute
SYNOPSIS
#include <pthread.h>
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
5.2.9 – pthread_attr_setprio
NAME
pthread_attr_setprio - Changes the scheduling priority attribute of
thread creation
SYNOPSIS
#include <pthread.h>
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
5.2.10 – pthread_attr_setsched
NAME
pthread_attr_setsched - Changes the scheduling policy attribute of
thread creation
SYNOPSIS
#include <pthread.h>
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
5.2.11 – pthread_attr_setstacksize
NAME
pthread_attr_setstacksize - Changes the stacksize attribute of
thread creation
SYNOPSIS
#include <pthread.h>
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
5.2.12 – pthread_cancel
NAME
pthread_cancel - Allows a thread to request that it or another
thread terminate execution
SYNOPSIS
#include <pthread.h>
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
5.2.13 – pthread_cleanup_pop
NAME
pthread_cleanup_pop - Removes the cleanup handler at the top of the
cleanup stack and optionally executes it
SYNOPSIS
#include <pthread.h>
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
5.2.14 – pthread_cleanup_push
NAME
pthread_cleanup_push - Establishes a cleanup handler
SYNOPSIS
#include <pthread.h>
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
5.2.15 – pthread_condattr_create
NAME
pthread_condattr_create - Creates a condition variable attributes
object
SYNOPSIS
#include <pthread.h>
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
5.2.16 – pthread_condattr_delete
NAME
pthread_condattr_delete - Deletes a condition variable attributes
object
SYNOPSIS
#include <pthread.h>
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
5.2.17 – pthread_cond_broadcast
NAME
pthread_cond_broadcast - Wakes all threads that are waiting on
a condition variable
SYNOPSIS
#include <pthread.h>
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
5.2.18 – pthread_cond_destroy
NAME
pthread_cond_destroy - Deletes a condition variable
SYNOPSIS
#include <pthread.h>
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
5.2.19 – pthread_cond_init
NAME
pthread_cond_init - Creates a condition variable
SYNOPSIS
#include <pthread.h>
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
5.2.20 – pthread_cond_signal
NAME
pthread_cond_signal - Wakes one thread that is waiting on a
condition variable
SYNOPSIS
#include <pthread.h>
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
5.2.21 – pthread_cond_timedwait
NAME
pthread_cond_timedwait - Causes a thread to wait for a condition
variable to be signaled or broadcast
SYNOPSIS
#include <pthread.h>
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
5.2.22 – pthread_cond_wait
NAME
pthread_cond_wait - Causes a thread to wait for a condition
variable to be signaled or broadcast
SYNOPSIS
#include <pthread.h>
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
5.2.23 – pthread_create
NAME
pthread_create - Creates a thread object and thread
SYNOPSIS
#include <pthread.h>
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
5.2.24 – pthread_delay_np
NAME
pthread_delay_np - Causes a thread to wait for a specified period
SYNOPSIS
#include <pthread.h>
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
5.2.25 – pthread_detach
NAME
pthread_detach - Marks a thread object for deletion
SYNOPSIS
#include <pthread.h>
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
5.2.26 – pthread_equal
NAME
pthread_equal - Compares one thread identifier to another thread
identifier.
SYNOPSIS
#include <pthread.h>
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
5.2.27 – pthread_exit
NAME
pthread_exit - Terminates the calling thread
SYNOPSIS
#include <pthread.h>
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
5.2.28 – pthread_getprio
NAME
pthread_getprio - Obtains the current priority of a thread
SYNOPSIS
#include <pthread.h>
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
5.2.29 – pthread_getscheduler
NAME
pthread_getscheduler - Obtains the current scheduling policy
of a thread
SYNOPSIS
#include <pthread.h>
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
5.2.30 – pthread_getspecific
NAME
pthread_getspecific - Obtains the thread-specific data associated
with the specified key
SYNOPSIS
#include <pthread.h>
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
5.2.31 – pthread_get_expiration_np
NAME
pthread_get_expiration_np - Obtains a value representing a desired
expiration time
SYNOPSIS
#include <pthread.h>
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
5.2.32 – pthread_join
NAME
pthread_join - Causes the calling thread to wait for the
termination of a specified thread
SYNOPSIS
#include <pthread.h>
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
5.2.33 – pthread_keycreate
NAME
pthread_keycreate - Generates a unique thread-specific data
key value
SYNOPSIS
#include <pthread.h>
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
5.2.34 – pthread_lock_global_np
NAME
pthread_lock_global_np - Locks the global mutex
SYNOPSIS
#include <pthread.h>
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
5.2.35 – pthread_mutexattr_create
NAME
pthread_mutexattr_create - Creates a mutex attributes object
SYNOPSIS
#include <pthread.h>
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
5.2.36 – pthread_mutexattr_delete
NAME
pthread_mutexattr_delete - Deletes a mutex attributes object
SYNOPSIS
#include <pthread.h>
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
5.2.37 – pthread_mutexattr_getkind_np
NAME
pthread_mutexattr_getkind_np - Obtains the mutex type attribute
used when a mutex is created
SYNOPSIS
#include <pthread.h>
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
5.2.38 – pthread_mutexattr_setkind_np
NAME
pthread_mutexattr_setkind_np - Specifies the mutex type attribute
SYNOPSIS
#include <pthread.h>
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
5.2.39 – pthread_mutex_destroy
NAME
pthread_mutex_destroy - Deletes a mutex
SYNOPSIS
#include <pthread.h>
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
5.2.40 – pthread_mutex_init
NAME
pthread_mutex_init - Creates a mutex
SYNOPSIS
#include <pthread.h>
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
5.2.41 – pthread_mutex_lock
NAME
pthread_mutex_lock - Locks an unlocked mutex
SYNOPSIS
#include <pthread.h>
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
5.2.42 – pthread_mutex_trylock
NAME
pthread_mutex_trylock - Locks a mutex
SYNOPSIS
#include <pthread.h>
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
5.2.43 – pthread_mutex_unlock
NAME
pthread_mutex_unlock - Unlocks a mutex
SYNOPSIS
#include <pthread.h>
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
5.2.44 – pthread_once
NAME
pthread_once - Calls an initialization routine executed by
one thread, a single time
SYNOPSIS
#include <pthread.h>
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.
5.2.45 – pthread_self
NAME
pthread_self - Obtains the identifier of the current thread
SYNOPSIS
#include <pthread.h>
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
5.2.46 – pthread_setasynccancel
NAME
pthread_setasynccancel - Enables or disables the current
thread's asynchronous cancelability
SYNOPSIS
#include <pthread.h>
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
5.2.47 – pthread_setcancel
NAME
pthread_setcancel - Enables or disables the current thread's
general cancelability
SYNOPSIS
#include <pthread.h>
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
5.2.48 – pthread_setprio
NAME
pthread_setprio - Changes the current priority of a thread
SYNOPSIS
#include <pthread.h>
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
5.2.49 – pthread_setscheduler
NAME
pthread_setscheduler - Changes the current scheduling policy
and priority of a thread
SYNOPSIS
#include <pthread.h>
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
5.2.50 – pthread_setspecific
NAME
pthread_setspecific - Sets the thread-specific data associated
with the specified key for the current thread
SYNOPSIS
#include <pthread.h>
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
5.2.51 – pthread_signal_to_cancel_np
NAME
pthread_signal_to_cancel_np - Cancels the specified thread
SYNOPSIS
#include <pthread.h>
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
5.2.52 – pthread_testcancel
NAME
pthread_testcancel - Requests delivery of a pending cancel to the
current thread
SYNOPSIS
#include <pthread.h>
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
5.2.53 – pthread_unlock_global_np
NAME
pthread_unlock_global_np - Unlocks a global mutex
SYNOPSIS
#include <pthread.h>
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
5.2.54 – pthread_yield
NAME
pthread_yield - Notifies the scheduler that the current thread
is willing to release its processor
SYNOPSIS
#include <pthread.h>
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
5.2.55 – sigwait
NAME
sigwait - Causes a thread to wait for an asynchronous signal
SYNOPSIS
#include <pthread.h>
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
6 – DCE_SECURITY
DCE Security Services provide authentication and authorization within a cell and is based upon MIT's Kerberos private key encryption system.
6.1 – 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.
6.1.1 – 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
6.1.2 – 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
6.1.3 – 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.
6.1.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
6.1.5 – 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
6.1.6 – 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
6.1.7 – 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.
6.1.7.1 – 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.
6.1.7.2 – 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.
6.1.7.3 – Messages
6.1.7.3.1 – EXP_ACCEXISTS
OpenVMS account for <principal> already exists
Explanation:
Could not export <principal> because it has already been
exported.
User Action:
None.
6.1.7.3.2 – EXP_ADDDCEACC
account for <principal> successfully added to OpenVMS
Explanation:
An OpenVMS acount was successfully created for <principal>.
User Action:
Note directly preceding and following messages for warnings.
6.1.7.3.3 – EXP_ADDDCEUAF
principal <principal> successfully added to DCE$UAF
Explanation:
Principal <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.1.7.3.4 – EXP_ADDUAF
principal <principal> successfully exported to OpenVMS
Explanation:
An OpenVMS account for successfully created for DCE
<principal>.
User Action:
Note directly preceding and following messages for warnings.
6.1.7.3.5 – 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.1.7.3.6 – EXP_CREDCEUAF
created new DCE$UAF file
Explanation:
A new DCE$UAF file was created.
User Action:
None.
6.1.7.3.7 – EXP_DCEERR
<DCE error message>
Explanation:
Accompanying DCE error message.
User Action:
Use this message to solve the problem generating the error.
6.1.7.3.8 – EXP_DCELOGIN
error in DCE login
Explanation:
Could not perform a DCE login.
User Action:
Enter valid DCE principal and password combination.
6.1.7.3.9 – EXP_DCEUAFERR
error searching DCE$UAF
Explanation:
Error searching or reading DCE$UAF file.
User Action:
Note accompanying error message for more details.
6.1.7.3.10 – EXP_DELDCEUAF
principal <principal> successfully deleted from DCE$UAF
Explanation:
Principal <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.1.7.3.11 – EXP_DISUSER
<username> remains DISUSER-ed
Explanation:
OpenVMS account for <username> was successfully created but
could not enable the account.
User Action:
Manually remove the DISUSER flag using the AUTHORIZE
utility.
6.1.7.3.12 – 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.1.7.3.13 – 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.1.7.3.14 – 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.1.7.3.15 – EXP_ERRCRACC
error creating OpenVMS account for <username>
Explanation:
Could not create an OpenVMS account for <username>.
User Action:
See accompanying error message for more details.
6.1.7.3.16 – 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.1.7.3.17 – EXP_ERRCREUAF
error creating OpenVMS account for <username> - see following
messages
Explanation:
Could not create the OpenVMS account for <username>.
User Action:
Note accompanying error messages for more details.
6.1.7.3.18 – 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.1.7.3.19 – 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.1.7.3.20 – 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.1.7.3.21 – EXP_ERRENAUSR
error enabling user <username>
Explanation:
Could not remove DISUSER flag from <username>'s account.
User Action:
Manually remove the flag using the AUTHORIZE utility.
6.1.7.3.22 – EXP_ERRQUOTA
error assigning disk quota to username <username> - see following
messages
Explanation:
Error(s) occurred while attempting to set up disk
quota for <username>
User Action:
Note the messages following this message.
6.1.7.3.23 – EXP_ERRSETPW
error setting password for <username>
Explanation:
Could not set password for OpenVMS <username>.
User Action:
Manually set password using the AUTHORIZE utility.
6.1.7.3.24 – 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.1.7.3.25 – EXP_ERRSYSUAF
error accessing SYSUAF file
Explanation:
Could not access the SYSUAF file.
User Action:
Note accompanying error message for more details.
6.1.7.3.26 – EXP_ERRUAFGET
error getting SYSUAF information
Explanation:
Error accessing information in the SYSUAF file.
User Action:
Note accompanying error message for more information.
6.1.7.3.27 – EXP_EXCADD
principal <principal> added to DCE EXPORT exclude list
Explanation:
Principal <principal> successfully added to the DCE EXPORT
exclude list.
User Action:
None.
6.1.7.3.28 – EXP_EXCDEL
principal <principal> removed from DCE EXPORT exclude list
Explanation:
Principal <principal> successfully deleted from the
DCE EXPORT exclude list.
User Action:
None.
6.1.7.3.29 – EXP_EXCLUDED
principal <principal> has been excluded from OpenVMS
Explanation:
Unable to export <principal> 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.1.7.3.30 – 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.1.7.3.31 – EXP_INDCEUAF
principal <principal> already in DCE$UAF
Explanation:
Could not add already existing principal name to DCE$UAF.
User Action:
None.
6.1.7.3.32 – EXP_INEXCLUDE
principal <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.1.7.3.33 – EXP_INITERROR
initialization error
Explanation:
Error during initialization phase for DCE EXPORT.
User Action:
Note accompanying error message for more details.
6.1.7.3.34 – EXP_INITWAIT
initializing.....
Explanation:
DCE EXPORT in initialization phase.
User Action:
None.
6.1.7.3.35 – EXP_INPREQ
input required!
Explanation:
Input not entered where mandatory.
User Action:
Provide input.
6.1.7.3.36 – 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.1.7.3.37 – 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.1.7.3.38 – EXP_INVGRPUIC
invalid group UIC
Explanation:
Group UIC entered is invalid (format if value, name if
identifier).
User Action:
Enter valid group UIC.
6.1.7.3.39 – EXP_INVMEMUIC
invalid member UIC
Explanation:
Member UIC entered is out of range or of invalid format.
User Action:
Enter valid member UIC.
6.1.7.3.40 – EXP_INVMS
principal <principal> already exported to OpenVMS
Explanation:
A record for <principal> already exists in the DCE$UAF file
indicating that is has already been exported.
User Action:
None.
6.1.7.3.41 – 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.1.7.3.42 – EXP_INVPWDLEN
password length must be between <minimum> and <maximum> characters
Explanation:
The user specified password for the OpenVMS account is
outside of the defined range.
User Action:
Specify a password of length between <minimum> and <maximum>
6.1.7.3.43 – EXP_NAMEINUSE
OpenVMS username <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.1.7.3.44 – 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.1.7.3.45 – EXP_NOEXCUSR
no excluded users
Explanation:
No principal names listed in the DCE EXPORT exclude file.
User Action:
None.
6.1.7.3.46 – EXP_NOSCHUSR
no principal <principal> in DCE registry
Explanation:
Principal <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.1.7.3.47 – 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.1.7.3.48 – EXP_NOSUCHPR
no DCE account <principal>
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.1.7.3.49 – EXP_NOTINEXC
principal <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.1.7.3.50 – EXP_NOVMSUSR
no OpenVMS user <username>
Explanation:
A nonexistent OpenVMS username was specified with the /LIKE
qualifier.
User Action:
Specify a valid OpenVMS username.
6.1.7.3.51 – 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.1.7.3.52 – 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.1.7.3.53 – EXP_SEEFILE
see file <file name> 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 <file name>
for the error messages.
User Action:
Read the file <file name> for error messages.
6.1.7.3.54 – 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.1.7.3.55 – EXP_TOOLONG
input for <qualifier> too long
Explanation:
Value of <qualifer> is longer than expected maximum size of
value.
User Action:
Enter a value that is within the valid size range.
6.1.7.3.56 – EXP_USERERR
error getting input from user
Explanation:
User entered invalid input.
User Action:
Enter valid input.
6.1.7.4 – 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.
6.1.7.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.
6.1.7.6 – EXIT
Exits the EXPORT utility. You can also exit EXPORT by
pressing the Ctrl/Z key.
Format:
EXIT
6.1.7.7 – 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.1.7.7.1 – 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.1.7.7.2 – 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.1.7.7.3 – Data Qualifiers
6.1.7.7.3.1 /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.
6.1.7.7.3.2 /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.
6.1.7.7.3.3 /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.
6.1.7.7.3.4 /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.
6.1.7.7.3.5 /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).
6.1.7.7.3.6 /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].
6.1.7.7.3.7 /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.
6.1.7.7.3.8 /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.
6.1.7.7.3.9 /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.
6.1.7.7.3.10 /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).
6.1.7.8 – 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.1.7.8.1 – 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.1.7.8.2 – Qualifiers
6.1.7.8.2.1 /ALL
/ALL
Specifies that all EXPORT exclude entries are to be
displayed. If you do not specify principal, then /ALL is
assumed.
6.1.7.8.2.2 /OUTPUT=output
/OUTPUT=output
Determines where the output is written.
The default is SYS$OUTPUT:.
6.1.8 – 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
6.1.8.1 – 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.
6.1.8.2 – 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>
6.1.8.3 – Messages
6.1.8.3.1 – IMP_ACCEXISTS
account for <principal> already exists in DCE
Explanation:
An attempt has been made to recreate an account for
<principal> in the DCE registry.
User Action:
None. This is a warning indicating that this suboperation
in the IMPORT operation was previously performed.
6.1.8.3.2 – IMP_ADDDCE
username <username> successfully imported into DCE
Explanation:
A DCE account has been successfully created for OpenVMS
username <username>.
User Action:
None.
6.1.8.3.3 – IMP_ADDDCEACC
account for <principal> successfully added to DCE
Explanation:
A DCE account was successfully created for <principal>.
User Action:
None. This is an informational message displayed only if
/INFORM is specified on the DCE IMPORT command line.
6.1.8.3.4 – IMP_ADDDCEPRN
principal <principal> successfully added to DCE
Explanation:
Principal <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.1.8.3.5 – IMP_ADDDCEUAF
username <username> successfully added to DCE$UAF
Explanation:
Username <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.1.8.3.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.1.8.3.7 – IMP_CREDCEUAF
created new DCE$UAF file
Explanation:
A new DCE$UAF file was created.
User Action:
None.
6.1.8.3.8 – IMP_DCEERR
<DCE error message>
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.1.8.3.9 – 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.1.8.3.10 – 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.1.8.3.11 – IMP_DELACC
account for principal <principal> deleted from DCE
Explanation:
DCE account for <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 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.1.8.3.12 – IMP_DELDCEUAF
username <username> successfully deleted from DCE$UAF
Explanation:
Username <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.1.8.3.13 – IMP_DELFRGRP
principal <principal> from group <group>
Explanation:
Principal <principal> was deleted from <group> 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.1.8.3.14 – IMP_DELFRORG
principal <principal> deleted from organization <organization>
Explanation:
Principal <principal> was deleted from <organization> 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.1.8.3.15 – IMP_DELPRN
principal <principal> deleted from DCE
Explanation:
Principal <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.1.8.3.16 – IMP_ERRADDGRP
error adding principal <principal> to group <group>
Explanation:
Could not add <principal> to <group> in the DCE registry.
User Action:
Note the accompanying DCE error message for more details.
6.1.8.3.17 – IMP_ERRADDORG
error adding principal <principal> to organization <organization>
Explanation:
Could not add <principal> to <organization> in DCE registry.
User Action:
Note the accompanying DCE error message for more details.
6.1.8.3.18 – 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.1.8.3.19 – 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.1.8.3.20 – 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.1.8.3.21 – IMP_ERRCRACC
error creating account for <principal>
Explanation:
Could not create a DCE account for <principal>.
User Action:
Note the accompanying DCE error message for more details.
6.1.8.3.22 – 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.1.8.3.23 – IMP_ERRCRPRN
error creating principal <principal>
Explanation:
Could not create a principal in the DCE registry.
User Action:
Note the accompanying DCE error message for more details.
6.1.8.3.24 – 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.1.8.3.25 – IMP_ERRDELACC
error deleting account for <principal>
Explanation:
Unable to delete account for <principal> from DCE registry.
User Action:
See accompanying DCE error message for more details.
6.1.8.3.26 – 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.1.8.3.27 – IMP_ERRDELFRGRP
error deleting principal <principal> from group <group>
Explanation:
An error occurred while deleting <principal>
from <group> 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.1.8.3.28 – IMP_ERRDELFRORG
error deleting principal <principal> from organization
<organization>
Explanation:
An error occurred while deleting <principal> from
<organization> 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.1.8.3.29 – IMP_ERRDELPRN
error deleting principal <principal>
Explanation:
Unable to delete <principal> from DCE registry
User Action:
See accompanying DCE error message for more details
6.1.8.3.30 – 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.1.8.3.31 – 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.1.8.3.32 – 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.1.8.3.33 – 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.1.8.3.34 – IMP_EXCADD
username <username> added to DCE IMPORT exclude list
Explanation:
Username <username> successfully added to the DCE IMPORT
exclude file. A DCE account will not be created for this
username.
User Action:
None.
6.1.8.3.35 – IMP_EXCDEL
username <username> removed from DCE IMPORT exclude list
Explanation:
Username <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.1.8.3.36 – IMP_EXCLUDED
username <username> has been excluded from DCE
Explanation:
Username <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.1.8.3.37 – IMP_INDCE
username <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.1.8.3.38 – IMP_INDCEUAF
user <username> already in DCE$UAF
Explanation:
Username <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.1.8.3.39 – IMP_INEXCLUDE
username <username> already in DCE IMPORT exclude file
Explanation:
Username <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.1.8.3.40 – 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.1.8.3.41 – 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.1.8.3.42 – IMP_INITWAIT
initializing.....
Explanation:
DCE IMPORT is in initialization mode.
User Action:
None.
6.1.8.3.43 – 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.1.8.3.44 – IMP_INPREQ
input required!
Explanation:
Input not entered where input was mandatory.
User Action:
Provide required input.
6.1.8.3.45 – IMP_INTERROR
internal error
Explanation:
DCE IMPORT internal error occurred.
User Action:
Contact your support engineer or Submit a Quality Assurance
Report (QAR).
6.1.8.3.46 – 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.1.8.3.47 – 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.1.8.3.48 – IMP_NOEXCUSR
no excluded users
Explanation:
No users listed in DCE IMPORT exclude file.
User Action:
None.
6.1.8.3.49 – 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.1.8.3.50 – 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.1.8.3.51 – IMP_NOPRIN
principal <principal> does not exist in DCE Registry
Explanation:
Principal <principal> does not exist in the DCE Registry.
This means that <principal> does not have a corresponding
OpenVMS username/account.
User Action:
None.
6.1.8.3.52 – 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.1.8.3.53 – IMP_NOSUCHGRP
no group <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.1.8.3.54 – IMP_NOSUCHORG
no organization <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.1.8.3.55 – 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.1.8.3.56 – IMP_NOSCHUSR
OpenVMS username <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.1.8.3.57 – 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.1.8.3.58 – IMP_PREXISTS
principal <principal> already exists in DCE
Explanation:
An attempt has been made to add <principal> to the DCE
registry.
User Action:
None. This is a warning indicating that this suboperation in
the IMPORT operation was previously performed.
6.1.8.3.59 – IMP_PRINGRP
principal <principal> already exists in group <group>
Explanation:
An attempt was made to add <principal> to DCE group <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.1.8.3.60 – IMP_PRINORG
principal <principal> already exists in organization <organization>
Explanation:
An attempt was made to add <principal> to DCE organization
<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.1.8.3.61 – IMP_PRINUSE
principal <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.1.8.3.62 – 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.1.8.3.63 – 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.1.8.3.64 – IMP_TOOLONG
input for <qualifier> too long
Explanation:
Value of <qualifer> is longer than expected maximum size of
value.
User Action:
Enter a value that is within the valid size range.
6.1.8.3.65 – IMP_USERERR
error getting input from user
Explanation:
Error occurred while getting user input.
User Action:
Provide valid input.
6.1.8.4 – 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.
6.1.8.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.
6.1.8.6 – EXIT
Exits the IMPORT utility. You can also exit IMPORT by
pressing the Ctrl/Z key.
Format:
EXIT
6.1.8.7 – 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.1.8.7.1 – 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.1.8.7.2 – Qualifiers
6.1.8.7.2.1 /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.
6.1.8.7.2.2 /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.
6.1.8.7.2.3 /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.
6.1.8.7.2.4 /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.
6.1.8.7.2.5 /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.
6.1.8.7.2.6 /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:.
6.1.8.7.2.7 /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.
6.1.8.7.2.8 /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.1.8.7.3 – Data Qualifiers
6.1.8.7.3.1 /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.
6.1.8.7.3.2 /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.
6.1.8.7.3.3 /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.
6.1.8.7.3.4 /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".
6.1.8.7.3.5 /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.
6.1.8.7.3.6 /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.
6.1.8.7.3.7 /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.
6.1.8.7.3.8 /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.
6.1.8.7.3.9 /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".
6.1.8.7.3.10 /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.
6.1.8.7.3.11 /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.
6.1.8.7.3.12 /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.
6.1.8.8 – 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.1.8.8.1 – 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.1.8.8.2 – Qualifiers
6.1.8.8.2.1 /ALL
/ALL
Specifies that all IMPORT exclude entries are to be
displayed. If you do not specify username, then /ALL is
assumed.
6.1.8.8.2.2 /OUTPUT=output
/OUTPUT=output
Determines where the output is written.
The default is SYS$OUTPUT:.
6.1.9 – 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.
6.1.9.1 – 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.1.9.1.1 – 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.1.9.1.2 – 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.1.9.1.3 – 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 <RETURN> 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.1.9.1.4 – 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.1.9.1.5 – 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.1.9.1.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.
6.1.9.2 – account_commands
ACCOUNT SUBCOMMANDS
6.1.9.2.1 – 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.1.9.2.2 – 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.1.9.2.3 – 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.1.9.2.4 – 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.1.9.2.5 – 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.
6.1.9.3 – key_management_commands
KEY MANAGEMENT SUBCOMMANDS The key management subcommands must be run in command-line mode.
6.1.9.3.1 – 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.1.9.3.2 – 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.1.9.3.3 – 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.
6.1.9.4 – miscellaneous_commands
Miscellaneous Commands
6.1.9.4.1 – 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.1.9.4.2 – 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.1.9.4.3 – properties
prop[erties] Changes or displays registry properties. This command prompts you for changes. Press <Return> to leave information unchanged.
6.1.9.4.4 – 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.1.9.4.5 – auth_policy
au[th_policy] Changes and/or displays registry authentication policies. This command prompts you for changes. Press <Return> to leave information unchanged.
6.1.9.4.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.1.9.4.7 – 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.1.9.4.8 – quit
q[uit] Exit rgy_edit.
6.1.9.4.9 – exit
e[xit] Exit rgy_edit.
6.1.9.4.10 – 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.1.9.4.11 – 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.
6.1.9.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.1.9.5.1 – view
v[iew] Displays local registry entries.
6.1.9.5.2 – delete
del[ete] principal_name Deletes the account and credential information for principal_name from the local registry.
6.1.9.5.3 – 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.1.9.5.4 – 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.
6.1.10 – 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
6.1.11 – 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>
6.1.12 – 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.
6.1.13 – 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.
6.2 – 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
6.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
6.3.1 – REGISTRY_API_DATA_TYPES
SYNOPSIS
#include <dce/rgybase.h>
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.
6.3.2 – EXTENDED_REGISTRY_ATTRIBUTE_DATA_TYPES
SYNOPSIS
#include <dce/sec_attr_base.h>
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.
6.3.3 – LOGIN_API_DATA_TYPES
SYNOPSIS
#include <dce/sec_login.h>
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.
6.3.4 – EXTENDED_PRIVILEGE_ATTRIBUTE_API_DATA_TYPES
SYNOPSIS
#include <dce/id_epac.h>
#include <dce/nbase.h>
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.
6.3.5 – ACL_API_DATA_TYPES
SYNOPSIS
#include <dce/aclbase.h>
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.
6.3.6 – 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 <dce/keymgmt.h>
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.
6.3.7 – ID_MAPPING_API_DATA_TYPES
SYNOPSIS
#include <dce/secidmap.h>
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.
6.3.8 – PASSWORD_MANAGEMENT_API_DATA_TYPES
SYNOPSIS
#include <dce/sec_pwd_mgmt.h>
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.
6.4 – API Routines
6.4.1 – rdacl_get_access
NAME
rdacl_get_access - Reads a privilege attribute certificate
SYNOPSIS
#include <dce/rdaclif.h>
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
6.4.2 – rdacl_get_manager_types
NAME
rdacl_get_manager_types - Lists the types of ACLs protecting an object
SYNOPSIS
#include <dce/rdaclif.h>
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
6.4.3 – 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 <dce/rdaclif.h>
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
6.4.4 – rdacl_get_printstring
NAME
rdacl_get_printstring - Returns printable ACL strings
SYNOPSIS
#include <dce/rdaclif.h>
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
6.4.5 – rdacl_get_referral
NAME
rdacl_get_referral - Gets a referral to an ACL update site
SYNOPSIS
#include <dce/rdaclif.h>
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
6.4.6 – rdacl_lookup
NAME
rdacl_lookup - Returns the ACL for an object
SYNOPSIS
#include <dce/rdaclif.h>
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
6.4.7 – rdacl_replace
NAME
rdacl_replace - Replaces an ACL
SYNOPSIS
#include <dce/rdaclif.h>
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
6.4.8 – rdacl_test_access
NAME
rdacl_test_access - Tests access to an object
SYNOPSIS
#include <dce/rdaclif.h>
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
6.4.9 – rdacl_test_access_on_behalf
NAME
rdacl_test_access_on_behalf - Tests access to an object on behalf of
another process
SYNOPSIS
#include <dce/rdaclif.h>
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
6.4.10 – sec_acl_bind
NAME
sec_acl_bind - Returns a handle for an object's ACL
SYNOPSIS
#include <dce/daclif.h>
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
6.4.11 – sec_acl_bind_to_addr
NAME
sec_acl_bind_to_addr - Returns a handle to an object identified by
its network address
SYNOPSIS
#include <dce/daclif.h>
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
6.4.12 – sec_acl_calc_mask
NAME
sec_acl_calc_mask - Returns the sec_acl_type_mask_obj entry for the
specified ACL list
SYNOPSIS
#include <dce/daclif.h>
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
6.4.13 – sec_acl_get_access
NAME
sec_acl_get_access - Lists the access (permission set) that the caller
has for an object
SYNOPSIS
#include <dce/daclif.h>
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
6.4.14 – sec_acl_get_error_info
NAME
sec_acl_get_error_info - Returns error information from an ACL handle
SYNOPSIS
#include <dce/daclif.h>
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
6.4.15 – sec_acl_get_manager_types
NAME
sec_acl_get_manager_types - Lists the manager types of the ACLs
protecting an object
SYNOPSIS
#include <dce/daclif.h>
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
6.4.16 – 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 <dce/daclif.h>
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
6.4.17 – sec_acl_get_printstring
NAME
sec_acl_get_printstring - Returns printable ACL strings
SYNOPSIS
#include <dce/daclif.h>
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
6.4.18 – sec_acl_lookup
NAME
sec_acl_lookup - Returns the ACL for an object
SYNOPSIS
#include <dce/daclif.h>
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
6.4.19 – sec_acl_release
NAME
sec_acl_release - Releases ACL storage
SYNOPSIS
#include <dce/daclif.h>
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
6.4.20 – sec_acl_release_handle
NAME
sec_acl_release_handle - Removes an ACL handle
SYNOPSIS
#include <dce/daclif.h>
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
6.4.21 – sec_acl_replace
NAME
sec_acl_replace - Replaces an ACL
SYNOPSIS
#include <dce/daclif.h>
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
6.4.22 – sec_acl_test_access
NAME
sec_acl_test_access - Tests access to an object
SYNOPSIS
#include <dce/daclif.h>
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
6.4.23 – 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 <dce/daclif.h>
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
6.4.24 – sec_attr_trig_query
NAME
sec_attr_trig_query - Reads attributes coded with an attribute trigger
type of query
SYNOPSIS
#include <dce/sec_attr_trig.h>
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
6.4.25 – 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 <dce/sec_attr_trig.h>
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
6.4.26 – 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 <dce/sec_cred.h>
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
6.4.27 – 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 <dce/sec_cred.h>
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
6.4.28 – 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 <dce/sec_cred.h>
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
6.4.29 – 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 <dce/sec_cred.h>
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
6.4.30 – sec_cred_get_client_princ_name
NAME
sec_cred_get_client_princ_name - Returns the principal name associated
with a credential handle
SYNOPSIS
#include <dce/sec_cred.h>
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
6.4.31 – sec_cred_get_deleg_restrictions
NAME
sec_cred_get_deleg_restrictions - Returns delegate restrictions
from a privilege attribute handle
SYNOPSIS
#include <dce/sec_cred.h>
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
6.4.32 – 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 <dce/sec_cred.h>
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
6.4.33 – sec_cred_get_delegation_type
NAME
sec_cred_get_delegation_type - Returns the delegation type from a
privilege attribute handle
SYNOPSIS
#include <dce/sec_cred.h>
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
6.4.34 – sec_cred_get_extended_attrs
NAME
sec_cred_get_extended_attrs - Returns extended attributes from a
privilege handle
SYNOPSIS
#include <dce/sec_cred.h>
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
6.4.35 – sec_cred_get_initiator
NAME
sec_cred_get_initiator - Returns the privilege attributes of the
initiator of a delegation chain
SYNOPSIS
#include <dce/sec_cred.h>
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
6.4.36 – sec_cred_get_opt_restrictions
NAME
sec_cred_get_opt_restrictions - Returns optional restrictions from
a privilege handle
SYNOPSIS
#include <dce/sec_cred.h>
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
6.4.37 – sec_cred_get_pa_data
NAME
sec_cred_get_pa_data - Returns identity information from a privilege
attribute handle
SYNOPSIS
#include <dce/sec_cred.h>
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
6.4.38 – sec_cred_get_req_restrictions
NAME
sec_cred_get_req_restrictions - Returns required restrictions
from a privilege attribute handle
SYNOPSIS
#include <dce/sec_cred.h>
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
6.4.39 – sec_cred_get_tgt_restrictions
NAME
sec_cred_get_tgt_restrictions - Returns target restrictions from a
privilege attribute handle
SYNOPSIS
#include <dce/sec_cred.h>
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
6.4.40 – sec_cred_get_v1_pac
NAME
sec_cred_get_v1_pac - Returns pre-1.1 PAC from a privilege attribute
handle
SYNOPSIS
#include <dce/sec_cred.h>
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
6.4.41 – 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 <dce/sec_cred.h>
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
6.4.42 – 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 <dce/sec_cred.h>
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
6.4.43 – 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 <dce/sec_cred.h>
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
6.4.44 – sec_id_gen_group
NAME
sec_id_gen_group - Generates a global name from cell and group UUIDs
SYNOPSIS
#include <dce/secidmap.h>
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
6.4.45 – sec_id_gen_name
NAME
sec_id_gen_name - Generates a global name from cell and principal
UUIDs
SYNOPSIS
#include <dce/secidmap.h>
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
6.4.46 – sec_id_parse_group
NAME
sec_id_parse_group - Translates a global name into group and cell
names and UUIDs
SYNOPSIS
#include <dce/secidmap.h>
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
6.4.47 – sec_id_parse_name
NAME
sec_id_parse_name - Translates a global name into principal and
cell names and UUIDs
SYNOPSIS
#include <dce/secidmap.h>
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
6.4.48 – sec_key_mgmt_change_key
NAME
sec_key_mgmt_change_key - Changes a principal's key
SYNOPSIS
#include <dce/keymgmt.h>
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
6.4.49 – sec_key_mgmt_delete_key
NAME
sec_key_mgmt_delete_key - Deletes a key from the local storage
SYNOPSIS
#include <dce/keymgmt.h>
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
6.4.50 – 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 <dce/keymgmt.h>
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
6.4.51 – sec_key_mgmt_free_key
NAME
sec_key_mgmt_free_key - Frees the memory used by a key value
SYNOPSIS
#include <dce/keymgmt.h>
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
6.4.52 – sec_key_mgmt_garbage_collect
NAME
sec_key_mgmt_garbage_collect - Deletes obsolete keys
SYNOPSIS
#include <dce/keymgmt.h>
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
6.4.53 – 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 <dce/keymgmt.h>
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
6.4.54 – sec_key_mgmt_get_key
NAME
sec_key_mgmt_get_key - Retrieves a key from local storage
SYNOPSIS
#include <dce/keymgmt.h>
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
6.4.55 – sec_key_mgmt_get_next_key
NAME
sec_key_mgmt_get_next_key - Retrieves successive keys from the local
key storage
SYNOPSIS
#include <dce/keymgmt.h>
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
6.4.56 – 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 <dce/keymgmt.h>
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
6.4.57 – sec_key_mgmt_initialize_cursor
NAME
sec_key_mgmt_initialize_cursor - Repositions the cursor in the local
key store
SYNOPSIS
#include <dce/keymgmt.h>
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
6.4.58 – sec_key_mgmt_manage_key
NAME
sec_key_mgmt_manage_key - Automatically changes a principal's key
before it expires
SYNOPSIS
#include <dce/keymgmt.h>
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
6.4.59 – sec_key_mgmt_release_cursor
NAME
sec_key_mgmt_release_cursor - Releases the memory used by an
initialized cursor value
SYNOPSIS
#include <dce/keymgmt.h>
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
6.4.60 – sec_key_mgmt_set_key
NAME
sec_key_mgmt_set_key - Inserts a key value into the local storage
SYNOPSIS
#include <dce/keymgmt.h>
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
6.4.61 – sec_login_become_delegate
NAME
sec_login_become_delegate - Causes an intermediate server to become a
delegate in traced delegation chain
SYNOPSIS
#include <dce/sec_login.h>
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
6.4.62 – sec_login_become_impersonator
NAME
sec_login_become_impersonator - Causes an intermediate server to
become a delegate in a simple
delegation chain
SYNOPSIS
#include <dce/sec_login.h>
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
6.4.63 – sec_login_become_initiator
NAME
sec_login_become_initiator - Constructs a new login context that
enables delegation for the calling client
SYNOPSIS
#include <dce/sec_login.h>
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
6.4.64 – sec_login_certify_identity
NAME
sec_login_certify_identity - Certifies the network
authentication service
SYNOPSIS
#include <dce/sec_login.h>
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
6.4.65 – 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 <dce/sec_login.h>
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
6.4.66 – sec_login_cred_get_initiator
NAME
sec_login_cred_get_initiator - Returns information about the
delegation initiator in a specified
login context
SYNOPSIS
#include <dce/sec_login.h>
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
6.4.67 – sec_login_cred_init_cursor
NAME
sec_login_cred_init_cursor - Initialize a sec_cred_cursor_t
SYNOPSIS
#include <dce/sec_cred.h>
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
6.4.68 – sec_login_disable_delegation
NAME
sec_login_disable_delegation - Disables delegation for a specified
login context
SYNOPSIS
#include <dce/sec_login.h>
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
6.4.69 – sec_login_export_context
NAME
sec_login_export_context - Creates an exportable login context
SYNOPSIS
#include <dce/sec_login.h>
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
6.4.70 – sec_login_free_net_info
NAME
sec_login_free_net_info - Frees storage allocated for a principal's
network information
SYNOPSIS
#include <dce/sec_login.h>
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
6.4.71 – sec_login_get_current_context
NAME
sec_login_get_current_context - Returns a handle to the current
login context
SYNOPSIS
#include <dce/sec_login.h>
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
6.4.72 – sec_login_get_expiration
NAME
sec_login_get_expiration - Returns the TGT lifetime for an
authenticated identity
SYNOPSIS
#include <dce/sec_login.h>
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
6.4.73 – sec_login_get_groups
NAME
sec_login_get_groups - Returns the groupset from a login context
SYNOPSIS
#include <dce/sec_login.h>
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
6.4.74 – sec_login_get_pwent
NAME
sec_login_get_pwent - Returns a passwd-style entry for a login context
SYNOPSIS
#include <dce/sec_login.h>
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 <pwd.h>
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
6.4.75 – sec_login_import_context
NAME
sec_login_import_context - Imports a login context
SYNOPSIS
#include <dce/sec_login.h>
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
6.4.76 – sec_login_init_first
NAME
sec_login_init_first - Initializes the default context
SYNOPSIS
#include <dce/sec_login.h>
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
6.4.77 – sec_login_inquire_net_info
NAME
sec_login_inquire_net_info - Returns a principal's network information
SYNOPSIS
#include <dce/sec_login.h>
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
6.4.78 – sec_login_newgroups
NAME
sec_login_newgroups - Changes the group list for a login context
SYNOPSIS
#include <dce/sec_login.h>
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
6.4.79 – sec_login_purge_context
NAME
sec_login_purge_context - Destroys a login context and frees its
storage
SYNOPSIS
#include <dce/sec_login.h>
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
6.4.80 – sec_login_refresh_identity
NAME
sec_login_refresh_identity - Refreshes an authenticated identity for
a login context
SYNOPSIS
#include <dce/sec_login.h>
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
6.4.81 – sec_login_release_context
NAME
sec_login_release_context - Frees storage allocated for a login
context
SYNOPSIS
#include <dce/sec_login.h>
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
6.4.82 – sec_login_set_context
NAME
sec_login_set_context - Creates network credentials for a login
context
SYNOPSIS
#include <dce/sec_login.h>
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
6.4.83 – sec_login_set_extended_attrs
NAME
sec_login_set_extended_attrs - Constructs a new login context that
contains extended registry attributes
SYNOPSIS
#include <dce/sec_login.h>
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
6.4.84 – sec_login_setup_first
NAME
sec_login_setup_first - Sets up the default network context
SYNOPSIS
#include <dce/sec_login.h>
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
6.4.85 – sec_login_setup_identity
NAME
sec_login_setup_identity - Sets up the user's network identity
SYNOPSIS
#include <dce/sec_login.h>
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
6.4.86 – sec_login_valid_and_cert_ident
NAME
sec_login_valid_and_cert_ident - Validates and certifies a login
context
SYNOPSIS
#include <dce/sec_login.h>
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(<user>,
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
6.4.87 – 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 <dce/sec_login.h>
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
6.4.88 – sec_login_validate_first
NAME
sec_login_validate_first - Validates the initial login context
SYNOPSIS
#include <dce/sec_login.h>
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
6.4.89 – sec_login_validate_identity
NAME
sec_login_validate_identity - Validates a login context's identity
SYNOPSIS
#include <dce/sec_login.h>
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
6.4.90 – sec_pwd_mgmt_free_handle
NAME
sec_pwd_mgmt_free_handle - Frees storage allocated for a
password management handle
SYNOPSIS
#include <dce/sec_pwd_mgmt.h>
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
6.4.91 – sec_pwd_mgmt_gen_pwd
NAME
sec_pwd_mgmt_gen_pwd - Generate a set of passwords
SYNOPSIS
#include <dce/sec_pwd_mgmt.h>
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
6.4.92 – sec_pwd_mgmt_get_val_type
NAME
sec_pwd_mgmt_get_val_type - Gets users password validation type
SYNOPSIS
#include <dce/sec_pwd_mgmt.h>
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
6.4.93 – sec_pwd_mgmt_setup
NAME
sec_pwd_mgmt_setup - Sets up the user's password policy information
SYNOPSIS
#include <dce/sec_pwd_mgmt.h>
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
6.4.94 – sec_rgy_acct_add
NAME
sec_rgy_acct_add - Adds an account for a login name
SYNOPSIS
#include <dce/acct.h>
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
6.4.95 – sec_rgy_acct_admin_replace
NAME
sec_rgy_acct_admin_replace - Replaces administrative account data
SYNOPSIS
#include <dce/acct.h>
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
6.4.96 – sec_rgy_acct_delete
NAME
sec_rgy_acct_delete - Deletes an account
SYNOPSIS
#include <dce/acct.h>
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
6.4.97 – sec_rgy_acct_get_projlist
NAME
sec_rgy_acct_get_projlist - Returns the projects in an account's
project list
SYNOPSIS
#include <dce/acct.h>
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
6.4.98 – sec_rgy_acct_lookup
NAME
sec_rgy_acct_lookup - Returns data for a specified account
SYNOPSIS
#include <dce/acct.h>
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
6.4.99 – sec_rgy_acct_passwd
NAME
sec_rgy_acct_passwd - Changes the password for an account
SYNOPSIS
#include <dce/acct.h>
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
6.4.100 – sec_rgy_acct_rename
NAME
sec_rgy_acct_rename - Changes an account login name
SYNOPSIS
#include <dce/acct.h>
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
6.4.101 – sec_rgy_acct_replace_all
NAME
sec_rgy_acct_replace_all - Replaces all account data for an account
SYNOPSIS
#include <dce/acct.h>
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
6.4.102 – sec_rgy_acct_user_replace
NAME
sec_rgy_acct_user_replace - Replaces user account data
SYNOPSIS
#include <dce/acct.h>
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
6.4.103 – 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 <dce/sec_rgy_attr.h>
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
6.4.104 – 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 <dce/sec_rgy_attr.h>
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
6.4.105 – 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 <dce/sec_rgy_attr.h>
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
6.4.106 – 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 <dce/sec_attr_base.h>
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
6.4.107 – sec_rgy_attr_delete
NAME
sec_rgy_attr_delete - Deletes specified attributes for a specified
object
SYNOPSIS
#include <dce/sec_rgy_attr.h>
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
6.4.108 – sec_rgy_attr_get_effective
NAME
sec_rgy_attr_get_effective - Reads effective attributes by ID
SYNOPSIS
#include <dce/sec_rgy_attr.h>
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
6.4.109 – 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 <dce/sec_rgy_attr.h>
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
6.4.110 – sec_rgy_attr_lookup_by_name
NAME
sec_rgy_attr_lookup_by_name - Read a single attribute instance for a
specific object
SYNOPSIS
#include <dce/sec_rgy_attr.h>
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
6.4.111 – 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 <dce/sec_rgy_attr.h>
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
6.4.112 – 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 <dce/dce_attr_base.h>
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
6.4.113 – sec_rgy_attr_sch_create_entry
NAME
sec_rgy_attr_sch_create_entry - Create a schema entry
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
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
6.4.114 – 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
6.4.115 – 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 <dce/sec_rgy_attr_sch.h>
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
6.4.116 – 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 <dce/sec_rgy_attr_sch.h>
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
6.4.117 – 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 <dce/sec_rgy_attr_sch.h>
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
6.4.118 – sec_rgy_attr_sch_delete_entry
NAME
sec_rgy_attr_sch_delete_entry - Delete a schema entry
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
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
6.4.119 – 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 <dce/sec_rgy_attr_sch.h>
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
6.4.120 – sec_rgy_attr_sch_lookup_by_id
NAME
sec_rgy_attr_sch_lookup_by_id - Read a schema entry identified by UUID
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
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
6.4.121 – sec_rgy_attr_sch_lookup_by_name
NAME
sec_rgy_attr_sch_lookup_by_name - Read a schema entry identified by
name
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
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
6.4.122 – sec_rgy_attr_sch_scan
NAME
sec_rgy_attr_sch_scan - Read a specified number of schema entries
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
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
6.4.123 – sec_rgy_attr_sch_update_entry
NAME
sec_rgy_attr_sch_update_entry - Update a schema entry
SYNOPSIS
#include <dce/sec_rgy_attr_sch.h>
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
6.4.124 – 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 <dce/sec_rgy_attr.h>
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
6.4.125 – sec_rgy_attr_update
NAME
sec_rgy_attr_update - Creates and updates attribute instances for a
specified object
SYNOPSIS
#include <dce/sec_rgy_attr.h>
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
6.4.126 – sec_rgy_auth_plcy_get_effective
NAME
sec_rgy_auth_plcy_get_effective - Returns the effective
authentication policy for an
account
SYNOPSIS
#include <dce/policy.h>
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
6.4.127 – sec_rgy_auth_plcy_get_info
NAME
sec_rgy_auth_plcy_get_info - Returns the authentication policy for
an account
SYNOPSIS
#include <dce/policy.h>
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
6.4.128 – sec_rgy_auth_plcy_set_info
NAME
sec_rgy_auth_plcy_set_info - Sets the authentication policy for an
account
SYNOPSIS
#include <dce/policy.h>
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
6.4.129 – sec_rgy_cell_bind
NAME
sec_rgy_cell_bind - Binds to a registry in a cell
SYNOPSIS
#include <dce/binding.h>
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
6.4.130 – sec_rgy_cursor_reset
NAME
sec_rgy_cursor_reset - Resets the registry database cursor
SYNOPSIS
#include <dce/misc.h>
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
6.4.131 – sec_rgy_login_get_effective
NAME
sec_rgy_login_get_effective - Returns the effective login data for
an account
SYNOPSIS
#include <dce/misc.h>
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
6.4.132 – sec_rgy_login_get_info
NAME
sec_rgy_login_get_info - Returns login information for an account
SYNOPSIS
#include <dce/misc.h>
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
6.4.133 – sec_rgy_pgo_add
NAME
sec_rgy_pgo_add - Adds a PGO item to the registry database
SYNOPSIS
#include <dce/pgo.h>
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
6.4.134 – sec_rgy_pgo_add_member
NAME
sec_rgy_pgo_add_member - Adds a person to a group or organization
SYNOPSIS
#include <dce/pgo.h>
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
6.4.135 – sec_rgy_pgo_delete
NAME
sec_rgy_pgo_delete - Deletes a PGO item from the registry database
SYNOPSIS
#include <dce/pgo.h>
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
6.4.136 – sec_rgy_pgo_delete_member
NAME
sec_rgy_pgo_delete_member - Deletes a member of a group or
organization
SYNOPSIS
#include <dce/pgo.h>
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
6.4.137 – 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 <dce/pgo.h>
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
6.4.138 – 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 <dce/pgo.h>
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
6.4.139 – sec_rgy_pgo_get_by_name
NAME
sec_rgy_pgo_get_by_name - Returns the data for a named PGO item
SYNOPSIS
#include <dce/pgo.h>
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
6.4.140 – 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 <dce/pgo.h>
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
6.4.141 – 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 <dce/pgo.h>
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
6.4.142 – sec_rgy_pgo_get_next
NAME
sec_rgy_pgo_get_next - Returns the next PGO item in the registry
database
SYNOPSIS
#include <dce/pgo.h>
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
6.4.143 – 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 <dce/pgo.h>
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
6.4.144 – 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 <dce/pgo.h>
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
6.4.145 – sec_rgy_pgo_is_member
NAME
sec_rgy_pgo_is_member - Checks group or organization membership
SYNOPSIS
#include <dce/pgo.h>
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
6.4.146 – sec_rgy_pgo_name_to_id
NAME
sec_rgy_pgo_name_to_id - Returns the UUID for a named PGO item
SYNOPSIS
#include <dce/pgo.h>
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
6.4.147 – 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 <dce/pgo.h>
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
6.4.148 – sec_rgy_pgo_rename
NAME
sec_rgy_pgo_rename - Changes the name of a PGO item in the registry
database
SYNOPSIS
#include <dce/pgo.h>
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
6.4.149 – sec_rgy_pgo_replace
NAME
sec_rgy_pgo_replace - Replaces the data in an existing PGO item
SYNOPSIS
#include <dce/pgo.h>
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
6.4.150 – 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 <dce/pgo.h>
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
6.4.151 – 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 <dce/pgo.h>
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
6.4.152 – sec_rgy_plcy_get_effective
NAME
sec_rgy_plcy_get_effective - Returns the effective policy for an
organization
SYNOPSIS
#include <dce/policy.h>
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
6.4.153 – sec_rgy_plcy_get_info
NAME
sec_rgy_plcy_get_info - Returns the policy for an organization
SYNOPSIS
#include <dce/policy.h>
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
6.4.154 – sec_rgy_plcy_set_info
NAME
sec_rgy_plcy_set_info - Sets the policy for an organization
SYNOPSIS
#include <dce/policy.h>
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
6.4.155 – sec_rgy_properties_get_info
NAME
sec_rgy_properties_get_info - Returns registry properties
SYNOPSIS
#include <dce/policy.h>
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
6.4.156 – sec_rgy_properties_set_info
NAME
sec_rgy_properties_set_info - Sets registry properties
SYNOPSIS
#include <dce/policy.h>
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
6.4.157 – sec_rgy_site_bind
NAME
sec_rgy_site_bind - Binds to a registry site
SYNOPSIS
#include <dce/binding.h>
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
6.4.158 – sec_rgy_site_bind_query
NAME
sec_rgy_site_bind_query - Binds to a registry query site
SYNOPSIS
#include <dce/binding.h>
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
6.4.159 – sec_rgy_site_bind_update
NAME
sec_rgy_site_bind_update - Binds to a registry update site
SYNOPSIS
#include <dce/binding.h>
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
6.4.160 – sec_rgy_site_binding_get_info
NAME
sec_rgy_site_binding_get_info - Returns information from the registry
binding handle
SYNOPSIS
#include <dce/binding.h>
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
6.4.161 – sec_rgy_site_close
NAME
sec_rgy_site_close - Frees the binding handle for a registry server
SYNOPSIS
#include <dce/binding.h>
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
6.4.162 – sec_rgy_site_get
NAME
sec_rgy_site_get - Returns the string representation for a bound
registry site
SYNOPSIS
#include <dce/binding.h>
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
6.4.163 – sec_rgy_site_is_readonly
NAME
sec_rgy_site_is_readonly - Checks whether a registry site is read-only
SYNOPSIS
#include <dce/binding.h>
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
6.4.164 – sec_rgy_site_open
NAME
sec_rgy_site_open - Binds to a registry site
SYNOPSIS
#include <dce/binding.h>
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
6.4.165 – sec_rgy_site_open_query
NAME
sec_rgy_site_open_query - Binds to a registry query site
SYNOPSIS
#include <dce/binding.h>
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
6.4.166 – sec_rgy_site_open_update
NAME
sec_rgy_site_open_update - Binds to a registry update site
SYNOPSIS
#include <dce/binding.h>
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
6.4.167 – 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 <dce/rgynbase.h>
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.
6.4.168 – 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 <dce/rgynbase.h>
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
6.4.169 – sec_rgy_unix_getpwnam
NAME
sec_rgy_unix_getpwnam - Returns a UNIX style passwd entry for account
matching the specified name.
SYNOPSIS
#include <dce/rgynbase.h>
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
6.4.170 – sec_rgy_unix_getpwuid
NAME
sec_rgy_unix_getpwuid - Returns a UNIX style passwd entry for
the account matching the specified UID
SYNOPSIS
#include <dce/rgynbase.h>
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
6.4.171 – 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 <dce/misc.h>
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
7 – 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
7.1 – 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
7.1.1 – 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.
7.1.2 – utc_abstime
NAME
utc_abstime - Computes the absolute value of a relative binary
timestamp
SYNOPSIS
#include <dce/utc.h>
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);
7.1.3 – utc_addtime
NAME
utc_addtime - Computes the sum of two binary timestamps
SYNOPSIS
#include <dce/utc.h>
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
7.1.4 – utc_anytime
NAME
utc_anytime - Converts a binary timestamp to a tm structure
SYNOPSIS
#include <dce/utc.h>
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
7.1.5 – utc_anyzone
NAME
utc_anyzone - Gets the time zone label and offset from GMT
SYNOPSIS
#include <dce/utc.h>
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
7.1.6 – utc_ascanytime
NAME
utc_ascanytime - Converts a binary timestamp to an ASCII string that
represents an arbitrary time zone
SYNOPSIS
#include <dce/utc.h>
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
7.1.7 – utc_ascgmtime
NAME
utc_ascgmtime - Converts a binary timestamp to an ASCII string that
expresses a GMT time
SYNOPSIS
#include <dce/utc.h>
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
7.1.8 – utc_asclocaltime
NAME
utc_asclocaltime - Converts a binary timestamp to an ASCII string that
represents a local time
SYNOPSIS
#include <dce/utc.h>
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
7.1.9 – utc_ascreltime
NAME
utc_ascreltime - Converts a relative binary timestamp to an ASCII
string that represents the time
SYNOPSIS
#include <dce/utc.h>
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
7.1.10 – utc_binreltime
NAME
utc_binreltime - Converts a relative binary timestamp to two timespec
structures that express relative time and inaccuracy
SYNOPSIS
#include <dce/utc.h>
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
7.1.11 – utc_bintime
NAME
utc_bintime - Converts a binary timestamp to a timespec structure
SYNOPSIS
#include <dce/utc.h>
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
7.1.12 – 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 <dce/utc.h>
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
7.1.13 – utc_cmpintervaltime
NAME
utc_cmpintervaltime - Compares two binary timestamps or two relative
binary timestamps
SYNOPSIS
#include <dce/utc.h>
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
7.1.14 – utc_cmpmidtime
NAME
utc_cmpmidtime - Compares two binary timestamps or two relative binary
timestamps, ignoring inaccuracies
SYNOPSIS
#include <dce/utc.h>
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
7.1.15 – utc_gettime
NAME
utc_gettime - Returns the current system time and inaccuracy as a
binary timestamp
SYNOPSIS
#include <dce/utc.h>
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.
7.1.16 – utc_getusertime
NAME
utc_getusertime - Returns the time and process-specific TDF, rather
than the system-specific TDF
SYNOPSIS
#include <dce/utc.h>
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
7.1.17 – utc_gmtime
NAME
utc_gmtime - Converts a binary timestamp to a tm structure that
expresses GMT or the equivalent UTC
SYNOPSIS
#include <dce/utc.h>
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
7.1.18 – utc_gmtzone
NAME
utc_gmtzone - Gets the time zone label for GMT
SYNOPSIS
#include <dce/utc.h>
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
7.1.19 – utc_localtime
NAME
utc_localtime - Converts a binary timestamp to a tm structure that
expresses local time
SYNOPSIS
#include <dce/utc.h>
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
7.1.20 – utc_localzone
NAME
utc_localzone - Gets the local time zone label and offset from GMT,
given utc
SYNOPSIS
#include <dce/utc.h>
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
7.1.21 – 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 <dce/utc.h>
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
7.1.22 – utc_mkascreltime
NAME
utc_mkascreltime - Converts a NULL-terminated character string that
represents a relative timestamp to a binary
timestamp
SYNOPSIS
#include <dce/utc.h>
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
7.1.23 – utc_mkasctime
NAME
utc_mkasctime - Converts a NULL-terminated character string that
represents an absolute timestamp to a binary
timestamp
SYNOPSIS
#include <dce/utc.h>
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
7.1.24 – utc_mkbinreltime
NAME
utc_mkbinreltime - Converts a timespec structure expressing a
relative time to a binary timestamp
SYNOPSIS
#include <dce/utc.h>
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
7.1.25 – utc_mkbintime
NAME
utc_mkbintime - Converts a timespec structure to a binary timestamp
SYNOPSIS
#include <dce/utc.h>
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
7.1.26 – utc_mkgmtime
NAME
utc_mkgmtime - Converts a tm structure that expresses GMT or UTC
to a binary timestamp
SYNOPSIS
#include <dce/utc.h>
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
7.1.27 – utc_mklocaltime
NAME
utc_mklocaltime - Converts a tm structure that expresses local time
to a binary timestamp
SYNOPSIS
#include <dce/utc.h>
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
7.1.28 – utc_mkreltime
NAME
utc_mkreltime - Converts a tm structure that expresses relative time
to a relative binary timestamp
SYNOPSIS
#include <dce/utc.h>
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 */
7.1.29 – utc_mulftime
NAME
utc_mulftime - Multiplies a relative binary timestamp by a
floating-point value.
SYNOPSIS
#include <dce/utc.h>
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
7.1.30 – utc_multime
NAME
utc_multime - Multiplies a relative binary timestamp by an integer
factor
SYNOPSIS
#include <dce/utc.h>
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
7.1.31 – utc_pointtime
NAME
utc_pointtime - Converts a binary timestamp to three binary
timestamps that represent the earliest, most
likely, and latest time
SYNOPSIS
#include <dce/utc.h>
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
7.1.32 – utc_reltime
NAME
utc_reltime - Converts a relative binary timestamp to a tm structure
SYNOPSIS
#include <dce/utc.h>
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
7.1.33 – 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 <dce/utc.h>
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
7.1.34 – utc_subtime
NAME
utc_subtime - Computes the difference between two binary timestamps
SYNOPSIS
#include <dce/utc.h>
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
7.2 – 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
7.2.1 – 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
7.2.2 – 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
7.2.3 – create
NAME
create - Creates the DCE DTS entity on the specified node
SYNOPSIS
dtscp create type <type>
OPTIONS
type <type> Specifies the type of DCE DTS entity to be created on
the specified node. Specify one of the following for
<type>:
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
7.2.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
7.2.5 – 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
7.2.6 – enable
NAME
enable - Starts the DTS entity on the local node.
SYNOPSIS
dtscp enable [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.
Valid values for <boolean> 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
7.2.7 – 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
7.2.8 – 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
7.2.9 – 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
7.2.10 – 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
7.2.11 – 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; <hostname>
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/<hostname>/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; <hostname> 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/<hostname>/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
7.2.12 – 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
7.2.13 – 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
7.2.14 – 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
7.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
7.4 – 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 PID from step 3 show>
$ dtsd :== $sys$system:dce$dtsd
$ dtsd -<arg1> [-<arg2>]
RELATED INFORMATION
Commands: dtscp
create
enable
Books: OSF DCE Administration Guide
8 – DCE_RPC
The Remote Procedure Call (RPC) service provides connections between individual procedures in an application across heterogeneous systems in a transparent way.
8.1 – 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.
8.2 – 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
8.2.1 – 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.
8.2.2 – 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).
8.2.3 – 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.
8.2.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.
8.2.4.1 – 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.
8.2.4.2 – 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()
8.2.4.3 – 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.
8.2.4.4 – 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.
8.2.4.4.1 – 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.
8.2.4.4.2 – 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;
8.2.4.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()
8.2.4.6 – 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.
8.2.4.7 – 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.
8.2.4.8 – 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()
8.2.4.9 – 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()
8.2.4.10 – 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.
8.2.4.11 – 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.
8.2.4.12 – 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.
8.2.4.13 – 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.
8.2.4.14 – 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.
8.2.4.15 – 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.
8.2.4.16 – 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]
8.2.4.16.1 – 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()
8.2.4.16.2 – 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 *.
8.2.4.16.3 – 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()
8.2.5 – 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.
8.2.6 – 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.
8.2.6.1 – 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()
8.2.6.2 – 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.
8.2.6.3 – 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.
8.2.6.4 – 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.
8.2.6.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.
8.2.6.6 – 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.
8.2.7 – 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
8.3 – Application Routines
These are the RPC application development routines.
8.3.1 – 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 <dce/codesets_stub.h>
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
8.3.2 – 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 <dce/codesets_stub.h>
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
8.3.3 – 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 <dce/codesets_stub.h>
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
8.3.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 <dce/codesets_stub.h>
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
8.3.5 – 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 <dce/rpc.h>
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
8.3.6 – 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 <dce/rpc.h>
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
8.3.7 – 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
8.3.8 – 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
8.3.9 – 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
8.3.10 – 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
8.3.11 – 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
8.3.12 – 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
8.3.13 – 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
8.3.14 – rpc_binding_copy
NAME
rpc_binding_copy - Returns a copy of a binding handle
Used by client or server applications.
SYNOPSIS
#include <dce/rpc.h>
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
8.3.15 – rpc_binding_free
NAME
rpc_binding_free - Releases binding handle resources
Used by client or server applications.
SYNOPSIS
#include <dce/rpc.h>
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
8.3.16 – 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 <dce/rpc.h>
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
8.3.17 – 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 <dce/rpc.h>
#include <dce/id_base.h>
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
8.3.18 – 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 <dce/rpc.h>
#include <dce/sec_login.h>
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
8.3.19 – 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 <dce/rpc.h>
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
8.3.20 – rpc_binding_reset
NAME
rpc_binding_reset - Resets a server binding handle
Used by client or management applications.
SYNOPSIS
#include <dce/rpc.h>
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
8.3.21 – 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 <dce/rpc.h>
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.
8.3.22 – 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 <dce/rpc.h>
#include <dce/sec_login.h>
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
8.3.23 – 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 <dce/rpc.h>
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
8.3.24 – 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 <dce/rpc.h>
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
8.3.25 – 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 <dce/rpc.h>
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
8.3.26 – 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 <dce/rpc.h>
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
8.3.27 – 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 <dce/rpc.h>
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
8.3.28 – 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 <dce/rpc.h>
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
8.3.29 – 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 <dce/rpc.h>
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
8.3.30 – 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 <dce/codesets_stub.h>
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.
8.3.31 – 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 <dce/rpc.h>
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.
8.3.32 – 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 <dce/rpc.h>
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.
8.3.33 – 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 <dce/rpc.h>
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
8.3.34 – rpc_ep_unregister
NAME
rpc_ep_unregister - Removes server address information from the
local endpoint map
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
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
8.3.35 – 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 <dce/rpc.h>
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
8.3.36 – 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 <dce/rpc.h>
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
8.3.37 – 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 <dce/rpc.h>
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
8.3.38 – 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 <dce/rpc.h>
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
8.3.39 – 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 <dce/rpc.h>
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
8.3.40 – rpc_mgmt_ep_unregister
NAME
rpc_mgmt_ep_unregister - Removes server address information from
an endpoint map
Used by management applications.
SYNOPSIS
#include <dce/rpc.h>
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
8.3.41 – 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 <dce/rpc.h>
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
8.3.42 – 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 <dce/rpc.h>
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
8.3.43 – 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 <dce/rpc.h>
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
8.3.44 – 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 <dce/rpc.h>
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
8.3.45 – rpc_mgmt_inq_stats
NAME
rpc_mgmt_inq_stats - Returns RPC runtime statistics
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
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
8.3.46 – 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 <dce/rpc.h>
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
8.3.47 – 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 <dce/rpc.h>
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
8.3.48 – 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 <dce/rpc.h>
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.
8.3.49 – 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 <dce/rpc.h>
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
8.3.50 – 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 <dce/rpc.h>
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
8.3.51 – rpc_mgmt_stats_vector_free
NAME
rpc_mgmt_stats_vector_free - Frees a statistics vector
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
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
8.3.52 – 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 <dce/rpc.h>(
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
8.3.53 – 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 <dce/rpc.h>(
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
8.3.54 – 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 <dce/rpc.h>(
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
8.3.55 – 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 <dce/rpc.h>(
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
8.3.56 – 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 <dce/rpc.h>(
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
8.3.57 – 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 <dce/rpc.h>
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
8.3.58 – 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 <dce/rpc.h>
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
8.3.59 – 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 <dce/rpc.h>
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
8.3.60 – 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 <dce/rpc.h>
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
8.3.61 – 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 <dce/rpc.h>
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
8.3.62 – 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 <dce/rpc.h>
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
8.3.63 – 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 <dce/rpc.h>
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
8.3.64 – 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 <dce/rpc.h>
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
8.3.65 – 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 <dce/rpc.h>
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.
8.3.66 – 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 <dce/rpc.h>
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
8.3.67 – 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 <dce/rpc.h>
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
8.3.68 – 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 <dce/rpc.h>
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
8.3.69 – rpc_ns_group_delete
NAME
rpc_ns_group_delete - Deletes a group attribute
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
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
8.3.70 – 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 <dce/rpc.h>
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
8.3.71 – 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 <dce/rpc.h>
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
8.3.72 – 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 <dce/rpc.h>
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
8.3.73 – 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 <dce/rpc.h>
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
8.3.74 – 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 <dce/rpc.h>
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
8.3.75 – 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 <dce/rpc.h>
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
8.3.76 – 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 <dce/rpc.h>
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
8.3.77 – 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 <dce/rpc.h>
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
8.3.78 – 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 <dce/rpc.h>
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
8.3.79 – 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 <dce/rpc.h>
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
8.3.80 – 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 <dce/rpc.h>
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
8.3.81 – 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 <dce/rpc.h>
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
8.3.82 – 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 <dce/rpc.h>
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
8.3.83 – 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 <dce/rpc.h>
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
8.3.84 – 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 <dce/rpc.h>
#include <dce/nsattrid.h>
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
8.3.85 – 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 <dce/rpc.h>
#include <dce/nsattrid.h>
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
8.3.86 – 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 <dce/rpc.h>
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
8.3.87 – rpc_ns_profile_delete
NAME
rpc_ns_profile_delete - Deletes a profile attribute
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
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
8.3.88 – 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 <dce/rpc.h>
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
8.3.89 – 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 <dce/rpc.h>
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
8.3.90 – 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 <dce/rpc.h>
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
8.3.91 – 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 <dce/rpc.h>
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
8.3.92 – 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 <dce/rpc.h>
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
8.3.93 – rpc_object_inq_type
NAME
rpc_object_inq_type - Returns the type of an object
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
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
8.3.94 – rpc_object_set_inq_fn
NAME
rpc_object_set_inq_fn - Registers an object inquiry function
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
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
8.3.95 – 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 <dce/rpc.h>
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
8.3.96 – 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 <dce/rpc.h>
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
8.3.97 – 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 <dce/rpc.h>
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
8.3.98 – 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 <dce/rpc.h>
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
8.3.99 – rpc_server_inq_bindings
NAME
rpc_server_inq_bindings - Returns binding handles for communications
with a server
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
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
8.3.100 – 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 <dce/rpc.h>
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
8.3.101 – rpc_server_listen
NAME
rpc_server_listen - Tells the RPC runtime to listen for remote
procedure calls
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
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.
8.3.102 – rpc_server_register_auth_info
NAME
rpc_server_register_auth_info - Registers authentication information
with the RPC runtime
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
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
8.3.103 – rpc_server_register_if
NAME
rpc_server_register_if - Registers an interface with the RPC runtime
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
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.
8.3.104 – rpc_server_unregister_if
NAME
rpc_server_unregister_if - Removes an interface from the RPC runtime
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
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
8.3.105 – 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 <dce/rpc.h>
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
8.3.106 – 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 <dce/rpc.h>
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
8.3.107 – 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 <dce/rpc.h>
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
8.3.108 – 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 <dce/rpc.h>
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
8.3.109 – 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 <dce/rpc.h>
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
8.3.110 – 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 <dce/rpc.h>
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.
8.3.111 – rpc_sm_allocate
NAME
rpc_sm_allocate - Allocates memory within the RPC stub memory
management scheme
SYNOPSIS
#include <rpc.h>
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
8.3.112 – rpc_sm_client_free
NAME
rpc_sm_client_free - Frees memory returned from a client stub
SYNOPSIS
#include <rpc.h>
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
8.3.113 – 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 <rpc.h>
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.
8.3.114 – rpc_sm_disable_allocate
NAME
rpc_sm_disable_allocate - Releases resources and allocated memory
within the stub memory management scheme
SYNOPSIS
#include <rpc.h>
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
8.3.115 – rpc_sm_enable_allocate
NAME
rpc_sm_enable_allocate - Enables the stub memory managment environment
SYNOPSIS
#include <rpc.h>
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
8.3.116 – rpc_sm_free
NAME
rpc_sm_free - Frees memory allocated by the rpc_sm_allocate routine
SYNOPSIS
#include <rpc.h>
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
8.3.117 – rpc_sm_get_thread_handle
NAME
rpc_sm_get_thread_handle - Gets a thread handle for the stub memory
management environment
SYNOPSIS
#include <rpc.h>
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
8.3.118 – 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 <rpc.h>
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
8.3.119 – rpc_sm_set_thread_handle
NAME
rpc_sm_set_thread_handle - Sets a thread handle for the stub memory
management environment
SYNOPSIS
#include <rpc.h>
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
8.3.120 – 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 <rpc.h>
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
8.3.121 – 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 <dce/rpc.h>
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
8.3.122 – 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 <rpc.h>
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
8.3.123 – rpc_ss_client_free
NAME
rpc_ss_client_free - Frees memory returned from a client stub
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
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
8.3.124 – 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 <dce/rpc.h>
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.
8.3.125 – rpc_ss_disable_allocate
NAME
rpc_ss_disable_allocate - Releases resources and allocated memory
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
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
8.3.126 – 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 <dce/rpc.h>
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
8.3.127 – 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 <dce/rpc.h>
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
8.3.128 – 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 <dce/rpc.h>
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 <pthread.h>
#include <idlbase.h>
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
8.3.129 – 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 <dce/rpc.h>
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
8.3.130 – 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 <dce/rpc.h>
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 <pthread.h>
#include <dce/idlbase.h>
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
8.3.131 – 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 <dce/rpc.h>
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
8.3.132 – 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 <dce/rpc.h>
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
8.3.133 – 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 <dce/rpc.h>
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
8.3.134 – rpc_string_free
NAME
rpc_string_free - Frees a character string allocated by the runtime
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
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
8.3.135 – uuid_compare
NAME
uuid_compare - Compares two UUIDs and determines their order
Used by client, server, or management applications.
SYNOPSIS
#include <dce/uuid.h>
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
8.3.136 – uuid_create
NAME
uuid_create - Creates a new UUID
Used by client, server, or management applications.
SYNOPSIS
#include <dce/uuid.h>
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
8.3.137 – uuid_create_nil
NAME
uuid_create_nil - Creates a nil UUID
Used by client, server, or management applications.
SYNOPSIS
#include <dce/uuid.h>
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
8.3.138 – uuid_equal
NAME
uuid_equal - Determines if two UUIDs are equal
Used by client, server, or management applications.
SYNOPSIS
#include <dce/uuid.h>
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
8.3.139 – uuid_from_string
NAME
uuid_from_string - Converts a string UUID to its binary representation
Used by client, server, or management applications.
SYNOPSIS
#include <dce/uuid.h>
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
8.3.140 – uuid_hash
NAME
uuid_hash - Creates a hash value for a UUID
Used by client, server, or management applications.
SYNOPSIS
#include <dce/uuid.h>
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.
8.3.141 – uuid_is_nil
NAME
uuid_is_nil - Determines if a UUID is nil
Used by client, server, or management applications.
SYNOPSIS
#include <dce/uuid.h>
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
8.3.142 – 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 <dce/uuid.h>
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
8.3.143 – 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 <dce/codesets_stub.h>
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
8.3.144 – 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 <dce/rpc.h>
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
8.3.145 – 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 <dce/rpc.h>
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
8.3.146 – 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 <dce/codesets_stub.h>
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
8.4 – 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
8.5 – 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]<file.ext>
All .idl or .h files that are part of DCE RPC
RELATED INFORMATION
Books: OSF DCE Application Development Guide
8.5.1 – ARGUMENTS
8.5.1.1 – -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.
8.5.1.2 – -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.
8.5.1.3 – -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
8.5.1.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.
8.5.1.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.
8.5.1.6 – -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.
8.5.1.7 – -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.
8.5.1.8 – -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.
8.5.1.9 – -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.
8.5.1.10 – -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.
8.5.1.11 – -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.
8.5.1.12 – -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.)
8.5.1.13 – -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 intro and rpc_server_register_if reference pages. See the OSF DCE Application Development Guide.)
8.5.1.14 – -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).
8.5.1.15 – -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.
8.5.1.16 – -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.
8.5.1.17 – -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.
8.5.1.18 – -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.
8.5.1.19 – -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.
8.5.1.20 – -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.
8.5.1.21 – -space_opt
-space_opt Generates code for the marshalling and unmarshalling of data that is optimized for space, rather than speed.
8.5.1.22 – -syntax_only
-syntax_only Checks only the syntax of the IDL file, but does not generate any output files.
8.5.1.23 – -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.
8.5.1.24 – -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).
8.5.1.25 – -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
8.5.1.26 – -version
- version Displays the current version of the IDL compiler.
8.5.1.27 – -v
-v Prints informational messages (verbose mode) on the screen while the compiler is running.
8.5.1.28 – -no_warn
-no_warn Suppresses compiler warning messages.
8.5.1.29 – -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.
8.5.1.30 – -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.
8.5.1.31 – -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.
8.5.1.32 – -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.
8.5.1.33 – -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.
8.5.1.34 – -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.
8.5.2 – 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
8.6 – 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.
8.6.1 – 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"
8.7 – 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
0x1251ace6,
0x93al,
0x11cd,
0x95,
0xad
{0x08, 0x00, 0x09, 0x70, 0x86, 0xe4}
};
RELATED_INFORMATION
Commands: uuidgen.
8.7.1 – 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.
8.8 – 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
8.8.1 – 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.
8.8.1.1 – 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
8.8.1.2 – 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
8.8.1.3 – 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
8.8.1.4 – 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
8.8.1.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
8.8.1.6 – 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
8.8.1.7 – 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
8.8.1.8 – 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
8.8.1.9 – 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
8.8.1.10 – 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
8.8.1.11 – 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
8.8.1.12 – 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
8.8.1.13 – 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
8.8.1.14 – 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
8.8.1.15 – 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
8.8.1.16 – 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
8.8.1.17 – 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
8.8.1.18 – 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
8.8.1.19 – 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
8.8.2 – 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.
8.8.3 – 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
_____________________________
8.8.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.
8.8.5 – 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.
8.8.5.1 – 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.
8.8.5.2 – 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.
8.8.5.3 – 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
8.8.5.4 – 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.
8.8.6 – 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
8.9 – 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.
9 – 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.
9.1 – 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
9.2 – 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
9.3 – cdscp
NAME cdscp - Starts the CDS control program SYNOPSIS cdscp [cdscp-command] ARGUMENTS See Command_Summary RELATED INFORMATION Books: OSF DCE Administration Guide
9.3.1 – 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
9.3.2 – 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
9.3.2.1 – 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 (=).
9.3.2.1.1 – 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
9.3.2.1.2 – 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.
9.3.2.1.3 – 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.
9.3.2.2 – 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.
9.3.2.3 – 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.
9.3.2.4 – 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.
9.3.3 – 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
9.3.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
9.3.5 – 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
9.3.6 – 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
9.3.7 – 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
9.3.8 – 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
9.3.9 – 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
9.3.10 – 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
9.3.11 – 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
9.3.12 – 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
9.3.13 – 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
9.3.14 – 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
9.3.15 – 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
9.3.16 – 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
9.3.17 – 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
9.3.18 – 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
9.3.19 – 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
9.3.20 – 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
9.3.21 – 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
9.3.22 – 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
9.3.23 – 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
9.3.24 – 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
9.3.25 – 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
9.3.26 – 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
9.3.27 – 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
9.3.28 – 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
9.3.29 – 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
9.3.30 – 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
9.3.31 – 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
9.3.32 – 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
9.3.33 – 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
9.3.34 – 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
9.3.35 – 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
9.3.36 – 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
9.3.37 – 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
9.3.38 – 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
9.3.39 – 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
9.3.40 – 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
9.3.41 – 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
9.3.42 – 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
9.3.43 – 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
9.3.44 – 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
9.3.45 – 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
9.3.46 – 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
9.3.47 – 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
9.3.47.1 – 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.
9.3.47.2 – 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
9.3.48 – 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
9.3.49 – 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
9.3.50 – 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
9.3.50.1 – 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.
9.3.50.2 – 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
9.3.51 – 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
RELATED INFORMATION
Command: disable server
9.4 – 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
9.5 – 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
9.6 – 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
9.7 – 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=<pid>
where pid is the process identifier of the gdad process.
RELATED INFORMATION
Books: OSF DCE Administration Guide
9.8 – 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
10 – 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.
10.1 – ARGUMENTS
10.1.1 – -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.
10.1.2 – -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.
10.1.3 – -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
10.1.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.
10.1.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.
10.1.6 – -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.
10.1.7 – -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.
10.1.8 – -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.
10.1.9 – -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.
10.1.10 – -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.
10.1.11 – -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.
10.1.12 – -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.)
10.1.13 – -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.)
10.1.14 – -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).
10.1.15 – -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.
10.1.16 – -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.
10.1.17 – -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.
10.1.18 – -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.
10.1.19 – -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.
10.1.20 – -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.
10.1.21 – -space_opt
-space_opt Generates code for the marshalling and unmarshalling of data that is optimized for space, rather than speed.
10.1.22 – -syntax_only
-syntax_only Checks only the syntax of the IDL file, but does not generate any output files.
10.1.23 – -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.
10.1.24 – -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).
10.1.25 – -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
10.1.26 – -version
-version Displays the current version of the IDL compiler.
10.1.27 – -v
-v Prints informational messages (verbose mode) on the screen while the compiler is running.
10.1.28 – -no_warn
-no_warn Suppresses compiler warning messages.
10.1.29 – -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.
10.1.30 – -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.
10.1.31 – -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.
10.1.32 – -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.
10.1.33 – -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.
10.1.34 – -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.
10.2 – 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
10.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 =
10.4 – 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
10.5 – 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]
10.6 – 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]...
10.6.1 – QUALIFIERS
10.6.1.1 /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.
10.6.1.2 /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.
10.6.1.3 /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.
10.6.1.4 /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.
10.6.1.5 /OUTPUT_DIRECTORY
/OUTPUT_DIRECTORY [=directory]
/NOOUTPUT_DIRECTORY (default)
This qualifier is equivalent to the -out directory
argument in the universal syntax.
10.6.1.6 /INCLUDE_DIRECTORY
/INCLUDE_DIRECTORY [=(pathname [,...])] (default)
/NOINCLUDE_DIRECTORY
These qualifiers are equivalent to the -Idirectory
and -no_def_idir arguments in the universal syntax.
10.6.1.7 /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.
10.6.1.8 /PREPROCESS
/PREPROCESS
/NOPREPROCESS (default)
These qualifiers are equivalent to the
-cpp_cmd 'c_preprocessor_command_line' and -no_cpp
arguments in the universal syntax.
10.6.1.9 /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.
10.6.1.10 /CC_QUALIFIERS
/CC_QUALIFIERS [="command-qualifiers"]
/NOCC_QUALIFIERS (default)
This qualifier is equivalent to the -cc_opt 'command_options'
argument in the universal syntax.
10.6.1.11 /DEFINE
/DEFINE [=(identifier[=definition][,...])]
/NODEFINE (default)
This qualifier is equivalent to the -Dname[=definition]
argument in the universal syntax.
10.6.1.12 /UNDEFINE
/UNDEFINE [=(identifier[,...])]
/NOUNDEFINE (default)
This qualifier is equivalent to the -Uname argument
in the universal syntax.
10.6.1.13 /OPTIMIZE
/OPTIMIZE [=({SPEED | SPACE })]
/OPTIMIZE = SPEED (default)
This qualifier is equivalent to the -space_opt
argument in the universal syntax.
10.6.1.14 /SYNTAX_ONLY
/SYNTAX_ONLY
/NOSYNTAX_ONLY (default)
This qualifier is equivalent to the -syntax_only
argument in the universal syntax.
10.6.1.15 /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.
10.6.1.16 /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.
10.6.1.17 /VERSION
/VERSION
/NOVERSION (default)
This qualifier is equivalent to the -version
argument in the universal syntax.
10.6.1.18 /LOG
/LOG
/NOLOG (default)
This qualifier is equivalent to the -v argument in
the universal syntax.
10.6.1.19 /WARNINGS
/WARNINGS (default)
/NOWARNINGS
This qualifier is equivalent to the -no_warn
argument in the universal syntax.
10.6.1.20 /VERIFY
/VERIFY
/NOVERIFY (default)
This qualifier is equivalent to the -confirm
argument in the universal syntax.
10.6.1.21 /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.
10.6.1.22 /LANGUAGE
/LANGUAGE [={CC | CXX | FORTRAN}]
/LANGUAGE=CC (default)
This qualifier is equivalent to the -lang argument in the
universal syntax.
10.6.1.23 /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.
10.7 – 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"
10.7.1 – 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.)
10.7.2 – 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)
10.8 – 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.
10.8.1 – 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"
11 – 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.