bfd: Looking Up or Entering a String
2.18.2 Looking up or entering a string
--------------------------------------
The function 'bfd_hash_lookup' is used both to look up a string in the
hash table and to create a new entry.
If the CREATE argument is 'FALSE', 'bfd_hash_lookup' will look up a
string. If the string is found, it will returns a pointer to a 'struct
bfd_hash_entry'. If the string is not found in the table
'bfd_hash_lookup' will return 'NULL'. You should not modify any of the
fields in the returns 'struct bfd_hash_entry'.
If the CREATE argument is 'TRUE', the string will be entered into the
hash table if it is not already there. Either way a pointer to a
'struct bfd_hash_entry' will be returned, either to the existing
structure or to a newly created one. In this case, a 'NULL' return
means that an error occurred.
If the CREATE argument is 'TRUE', and a new entry is created, the
COPY argument is used to decide whether to copy the string onto the hash
table objalloc or not. If COPY is passed as 'FALSE', you must be
careful not to deallocate or modify the string as long as the hash table
exists.