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: