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:
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
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 – 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.
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.
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.
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.
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.
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.
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.
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.
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