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.