bfd/hash.c

   1 /* hash.c -- hash table routines for BFD
   2    Copyright (C) 1993, 94 Free Software Foundation, Inc.
   3    Written by Steve Chamberlain <sac@cygnus.com>
   4
   5 This file is part of BFD, the Binary File Descriptor library.
   6
   7 This program is free software; you can redistribute it and/or modify
   8 it under the terms of the GNU General Public License as published by
   9 the Free Software Foundation; either version 2 of the License, or
  10 (at your option) any later version.
  11
  12 This program is distributed in the hope that it will be useful,
  13 but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15 GNU General Public License for more details.
  16
  17 You should have received a copy of the GNU General Public License
  18 along with this program; if not, write to the Free Software
  19 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.  */
  20
  21 #include "bfd.h"
  22 #include "sysdep.h"
  23 #include "libbfd.h"
  24 #include "obstack.h"
  25
  26 /*
  27 SECTION
  28         Hash Tables
  29
  30 @cindex Hash tables
  31         BFD provides a simple set of hash table functions.  Routines
  32         are provided to initialize a hash table, to free a hash table,
  33         to look up a string in a hash table and optionally create an
  34         entry for it, and to traverse a hash table.  There is
  35         currently no routine to delete an string from a hash table.
  36
  37         The basic hash table does not permit any data to be stored
  38         with a string.  However, a hash table is designed to present a
  39         base class from which other types of hash tables may be
  40         derived.  These derived types may store additional information
  41         with the string.  Hash tables were implemented in this way,
  42         rather than simply providing a data pointer in a hash table
  43         entry, because they were designed for use by the linker back
  44         ends.  The linker may create thousands of hash table entries,
  45         and the overhead of allocating private data and storing and
  46         following pointers becomes noticeable.
  47
  48         The basic hash table code is in <<hash.c>>.
  49
  50 @menu
  51 @* Creating and Freeing a Hash Table::
  52 @* Looking Up or Entering a String::
  53 @* Traversing a Hash Table::
  54 @* Deriving a New Hash Table Type::
  55 @end menu
  56
  57 INODE
  58 Creating and Freeing a Hash Table, Looking Up or Entering a String, Hash Tables, Hash Tables
  59 SUBSECTION
  60         Creating and freeing a hash table
  61
  62 @findex bfd_hash_table_init
  63 @findex bfd_hash_table_init_n
  64         To create a hash table, create an instance of a <<struct
  65         bfd_hash_table>> (defined in <<bfd.h>>) and call
  66         <<bfd_hash_table_init>> (if you know approximately how many
  67         entries you will need, the function <<bfd_hash_table_init_n>>,
  68         which takes a @var{size} argument, may be used).
  69         <<bfd_hash_table_init>> returns <<false>> if some sort of
  70         error occurs.
  71
  72 @findex bfd_hash_newfunc
  73         The function <<bfd_hash_table_init>> take as an argument a
  74         function to use to create new entries.  For a basic hash
  75         table, use the function <<bfd_hash_newfunc>>.  @xref{Deriving
  76         a New Hash Table Type} for why you would want to use a
  77         different value for this argument.
  78
  79 @findex bfd_hash_allocate
  80         <<bfd_hash_table_init>> will create an obstack which will be
  81         used to allocate new entries.  You may allocate memory on this
  82         obstack using <<bfd_hash_allocate>>.
  83
  84 @findex bfd_hash_table_free
  85         Use <<bfd_hash_table_free>> to free up all the memory that has
  86         been allocated for a hash table.  This will not free up the
  87         <<struct bfd_hash_table>> itself, which you must provide.
  88
  89 INODE
  90 Looking Up or Entering a String, Traversing a Hash Table, Creating and Freeing a Hash Table, Hash Tables
  91 SUBSECTION
  92         Looking up or entering a string
  93
  94 @findex bfd_hash_lookup
  95         The function <<bfd_hash_lookup>> is used both to look up a
  96         string in the hash table and to create a new entry.
  97
  98         If the @var{create} argument is <<false>>, <<bfd_hash_lookup>>
  99         will look up a string.  If the string is found, it will
 100         returns a pointer to a <<struct bfd_hash_entry>>.  If the
 101         string is not found in the table <<bfd_hash_lookup>> will
 102         return <<NULL>>.  You should not modify any of the fields in
 103         the returns <<struct bfd_hash_entry>>.
 104
 105         If the @var{create} argument is <<true>>, the string will be
 106         entered into the hash table if it is not already there.
 107         Either way a pointer to a <<struct bfd_hash_entry>> will be
 108         returned, either to the existing structure or to a newly
 109         created one.  In this case, a <<NULL>> return means that an
 110         error occurred.
 111
 112         If the @var{create} argument is <<true>>, and a new entry is
 113         created, the @var{copy} argument is used to decide whether to
 114         copy the string onto the hash table obstack or not.  If
 115         @var{copy} is passed as <<false>>, you must be careful not to
 116         deallocate or modify the string as long as the hash table
 117         exists.
 118
 119 INODE
 120 Traversing a Hash Table, Deriving a New Hash Table Type, Looking Up or Entering a String, Hash Tables
 121 SUBSECTION
 122         Traversing a hash table
 123
 124 @findex bfd_hash_traverse
 125         The function <<bfd_hash_traverse>> may be used to traverse a
 126         hash table, calling a function on each element.  The traversal
 127         is done in a random order.
 128
 129         <<bfd_hash_traverse>> takes as arguments a function and a
 130         generic <<void *>> pointer.  The function is called with a
 131         hash table entry (a <<struct bfd_hash_entry *>>) and the
 132         generic pointer passed to <<bfd_hash_traverse>>.  The function
 133         must return a <<boolean>> value, which indicates whether to
 134         continue traversing the hash table.  If the function returns
 135         <<false>>, <<bfd_hash_traverse>> will stop the traversal and
 136         return immediately.
 137
 138 INODE
 139 Deriving a New Hash Table Type, , Traversing a Hash Table, Hash Tables
 140 SUBSECTION
 141         Deriving a new hash table type
 142
 143         Many uses of hash tables want to store additional information
 144         which each entry in the hash table.  Some also find it
 145         convenient to store additional information with the hash table
 146         itself.  This may be done using a derived hash table.
 147
 148         Since C is not an object oriented language, creating a derived
 149         hash table requires sticking together some boilerplate
 150         routines with a few differences specific to the type of hash
 151         table you want to create.
 152
 153         An example of a derived hash table is the linker hash table.
 154         The structures for this are defined in <<bfdlink.h>>.  The
 155         functions are in <<linker.c>>.
 156
 157         You may also derive a hash table from an already derived hash
 158         table.  For example, the a.out linker backend code uses a hash
 159         table derived from the linker hash table.
 160
 161 @menu
 162 @* Define the Derived Structures::
 163 @* Write the Derived Creation Routine::
 164 @* Write Other Derived Routines::
 165 @end menu
 166
 167 INODE
 168 Define the Derived Structures, Write the Derived Creation Routine, Deriving a New Hash Table Type, Deriving a New Hash Table Type
 169 SUBSUBSECTION
 170         Define the derived structures
 171
 172         You must define a structure for an entry in the hash table,
 173         and a structure for the hash table itself.
 174
 175         The first field in the structure for an entry in the hash
 176         table must be of the type used for an entry in the hash table
 177         you are deriving from.  If you are deriving from a basic hash
 178         table this is <<struct bfd_hash_entry>>, which is defined in
 179         <<bfd.h>>.  The first field in the structure for the hash
 180         table itself must be of the type of the hash table you are
 181         deriving from itself.  If you are deriving from a basic hash
 182         table, this is <<struct bfd_hash_table>>.
 183
 184         For example, the linker hash table defines <<struct
 185         bfd_link_hash_entry>> (in <<bfdlink.h>>).  The first field,
 186         <<root>>, is of type <<struct bfd_hash_entry>>.  Similarly,
 187         the first field in <<struct bfd_link_hash_table>>, <<table>>,
 188         is of type <<struct bfd_hash_table>>.
 189
 190 INODE
 191 Write the Derived Creation Routine, Write Other Derived Routines, Define the Derived Structures, Deriving a New Hash Table Type
 192 SUBSUBSECTION
 193         Write the derived creation routine
 194
 195         You must write a routine which will create and initialize an
 196         entry in the hash table.  This routine is passed as the
 197         function argument to <<bfd_hash_table_init>>.
 198
 199         In order to permit other hash tables to be derived from the
 200         hash table you are creating, this routine must be written in a
 201         standard way.
 202
 203         The first argument to the creation routine is a pointer to a
 204         hash table entry.  This may be <<NULL>>, in which case the
 205         routine should allocate the right amount of space.  Otherwise
 206         the space has already been allocated by a hash table type
 207         derived from this one.
 208
 209         After allocating space, the creation routine must call the
 210         creation routine of the hash table type it is derived from,
 211         passing in a pointer to the space it just allocated.  This
 212         will initialize any fields used by the base hash table.
 213
 214         Finally the creation routine must initialize any local fields
 215         for the new hash table type.
 216
 217         Here is a boilerplate example of a creation routine.
 218         @var{function_name} is the name of the routine.
 219         @var{entry_type} is the type of an entry in the hash table you
 220         are creating.  @var{base_newfunc} is the name of the creation
 221         routine of the hash table type your hash table is derived
 222         from.
 223
 224 EXAMPLE
 225
 226 .struct bfd_hash_entry *
 227 .@var{function_name} (entry, table, string)
 228 .     struct bfd_hash_entry *entry;
 229 .     struct bfd_hash_table *table;
 230 .     const char *string;
 231 .{
 232 .  struct @var{entry_type} *ret = (@var{entry_type} *) entry;
 233 .
 234 . {* Allocate the structure if it has not already been allocated by a
 235 .    derived class.  *}
 236 .  if (ret == (@var{entry_type} *) NULL)
 237 .    ret = ((@var{entry_type} *)
 238 .          bfd_hash_allocate (table, sizeof (@var{entry_type})));
 239 .
 240 . {* Call the allocation method of the base class.  *}
 241 .  ret = ((@var{entry_type} *)
 242 .        @var{base_newfunc} ((struct bfd_hash_entry *) ret, table, string));
 243 .
 244 . {* Initialize the local fields here.  *}
 245 .
 246 .  return (struct bfd_hash_entry *) ret;
 247 .}
 248
 249 DESCRIPTION
 250         The creation routine for the linker hash table, which is in
 251         <<linker.c>>, looks just like this example.
 252         @var{function_name} is <<_bfd_link_hash_newfunc>>.
 253         @var{entry_type} is <<struct bfd_link_hash_entry>>.
 254         @var{base_newfunc} is <<bfd_hash_newfunc>>, the creation
 255         routine for a basic hash table.
 256
 257         <<_bfd_link_hash_newfunc>> also initializes the local fields
 258         in a linker hash table entry: <<type>>, <<written>> and
 259         <<next>>.
 260
 261 INODE
 262 Write Other Derived Routines, , Write the Derived Creation Routine, Deriving a New Hash Table Type
 263 SUBSUBSECTION
 264         Write other derived routines
 265
 266         You will want to write other routines for your new hash table,
 267         as well.
 268
 269         You will want an initialization routine which calls the
 270         initialization routine of the hash table you are deriving from
 271         and initializes any other local fields.  For the linker hash
 272         table, this is <<_bfd_link_hash_table_init>> in <<linker.c>>.
 273
 274         You will want a lookup routine which calls the lookup routine
 275         of the hash table you are deriving from and casts the result.
 276         The linker hash table uses <<bfd_link_hash_lookup>> in
 277         <<linker.c>> (this actually takes an additional argument which
 278         it uses to decide how to return the looked up value).
 279
 280         You may want a traversal routine.  This should just call the
 281         traversal routine of the hash table you are deriving from with
 282         appropriate casts.  The linker hash table uses
 283         <<bfd_link_hash_traverse>> in <<linker.c>>.
 284
 285         These routines may simply be defined as macros.  For example,
 286         the a.out backend linker hash table, which is derived from the
 287         linker hash table, uses macros for the lookup and traversal
 288         routines.  These are <<aout_link_hash_lookup>> and
 289         <<aout_link_hash_traverse>> in aoutx.h.
 290 */
 291
 292 /* Obstack allocation and deallocation routines.  */
 293 #define obstack_chunk_alloc malloc
 294 #define obstack_chunk_free free
 295
 296 /* The default number of entries to use when creating a hash table.  */
 297 #define DEFAULT_SIZE (4051)
 298
 299 /* Create a new hash table, given a number of entries.  */
 300
 301 boolean
 302 bfd_hash_table_init_n (table, newfunc, size)
 303      struct bfd_hash_table *table;
 304      struct bfd_hash_entry *(*newfunc) PARAMS ((struct bfd_hash_entry *,
 305                                                 struct bfd_hash_table *,
 306                                                 const char *));
 307      unsigned int size;
 308 {
 309   unsigned int alloc;
 310
 311   alloc = size * sizeof (struct bfd_hash_entry *);
 312   if (!obstack_begin (&table->memory, alloc))
 313     {
 314       bfd_error = no_memory;
 315       return false;
 316     }
 317   table->table = ((struct bfd_hash_entry **)
 318                   obstack_alloc (&table->memory, alloc));
 319   if (!table->table)
 320     {
 321       bfd_error = no_memory;
 322       return false;
 323     }
 324   memset ((PTR) table->table, 0, alloc);
 325   table->size = size;
 326   table->newfunc = newfunc;
 327   return true;
 328 }
 329
 330 /* Create a new hash table with the default number of entries.  */
 331
 332 boolean
 333 bfd_hash_table_init (table, newfunc)
 334      struct bfd_hash_table *table;
 335      struct bfd_hash_entry *(*newfunc) PARAMS ((struct bfd_hash_entry *,
 336                                                 struct bfd_hash_table *,
 337                                                 const char *));
 338 {
 339   return bfd_hash_table_init_n (table, newfunc, DEFAULT_SIZE);
 340 }
 341
 342 /* Free a hash table.  */
 343
 344 void
 345 bfd_hash_table_free (table)
 346      struct bfd_hash_table *table;
 347 {
 348   obstack_free (&table->memory, (PTR) NULL);
 349 }
 350
 351 /* Look up a string in a hash table.  */
 352
 353 struct bfd_hash_entry *
 354 bfd_hash_lookup (table, string, create, copy)
 355      struct bfd_hash_table *table;
 356      const char *string;
 357      boolean create;
 358      boolean copy;
 359 {
 360   register const unsigned char *s;
 361   register unsigned long hash;
 362   register unsigned int c;
 363   struct bfd_hash_entry *hashp;
 364   unsigned int len;
 365   unsigned int index;
 366
 367   hash = 0;
 368   len = 0;
 369   s = (const unsigned char *) string;
 370   while ((c = *s++) != '\0')
 371     {
 372       hash += c + (c << 17);
 373       hash ^= hash >> 2;
 374       ++len;
 375     }
 376   hash += len + (len << 17);
 377   hash ^= hash >> 2;
 378
 379   index = hash % table->size;
 380   for (hashp = table->table[index];
 381        hashp != (struct bfd_hash_entry *) NULL;
 382        hashp = hashp->next)
 383     {
 384       if (hashp->hash == hash
 385           && strcmp (hashp->string, string) == 0)
 386         return hashp;
 387     }
 388
 389   if (! create)
 390     return (struct bfd_hash_entry *) NULL;
 391
 392   hashp = (*table->newfunc) ((struct bfd_hash_entry *) NULL, table, string);
 393   if (hashp == (struct bfd_hash_entry *) NULL)
 394     return (struct bfd_hash_entry *) NULL;
 395   if (copy)
 396     {
 397       char *new;
 398
 399       new = (char *) obstack_alloc (&table->memory, len + 1);
 400       if (!new)
 401         {
 402           bfd_error = no_memory;
 403           return (struct bfd_hash_entry *) NULL;
 404         }
 405       strcpy (new, string);
 406       string = new;
 407     }
 408   hashp->string = string;
 409   hashp->hash = hash;
 410   hashp->next = table->table[index];
 411   table->table[index] = hashp;
 412
 413   return hashp;
 414 }
 415
 416 /* Base method for creating a new hash table entry.  */
 417
 418 /*ARGSUSED*/
 419 struct bfd_hash_entry *
 420 bfd_hash_newfunc (entry, table, string)
 421      struct bfd_hash_entry *entry;
 422      struct bfd_hash_table *table;
 423      const char *string;
 424 {
 425   if (entry == (struct bfd_hash_entry *) NULL)
 426     entry = ((struct bfd_hash_entry *)
 427              bfd_hash_allocate (table, sizeof (struct bfd_hash_entry)));
 428   return entry;
 429 }
 430
 431 /* Allocate space in a hash table.  */
 432
 433 PTR
 434 bfd_hash_allocate (table, size)
 435      struct bfd_hash_table *table;
 436      unsigned int size;
 437 {
 438   return obstack_alloc (&table->memory, size);
 439 }
 440
 441 /* Traverse a hash table.  */
 442
 443 void
 444 bfd_hash_traverse (table, func, info)
 445      struct bfd_hash_table *table;
 446      boolean (*func) PARAMS ((struct bfd_hash_entry *, PTR));
 447      PTR info;
 448 {
 449   unsigned int i;
 450
 451   for (i = 0; i < table->size; i++)
 452     {
 453       struct bfd_hash_entry *p;
 454
 455       for (p = table->table[i]; p != NULL; p = p->next)
 456         {
 457           if (! (*func) (p, info))
 458             return;
 459         }
 460     }
 461 }