bfd/opncls.c

   1 /* opncls.c -- open and close a BFD.
   2    Copyright (C) 1990-2017 Free Software Foundation, Inc.
   3
   4    Written by Cygnus Support.
   5
   6    This file is part of BFD, the Binary File Descriptor library.
   7
   8    This program is free software; you can redistribute it and/or modify
   9    it under the terms of the GNU General Public License as published by
  10    the Free Software Foundation; either version 3 of the License, or
  11    (at your option) any later version.
  12
  13    This program is distributed in the hope that it will be useful,
  14    but WITHOUT ANY WARRANTY; without even the implied warranty of
  15    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16    GNU General Public License for more details.
  17
  18    You should have received a copy of the GNU General Public License
  19    along with this program; if not, write to the Free Software
  20    Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston,
  21    MA 02110-1301, USA.  */
  22
  23 #include "sysdep.h"
  24 #include "bfd.h"
  25 #include "objalloc.h"
  26 #include "libbfd.h"
  27 #include "libiberty.h"
  28 #include "elf-bfd.h"
  29
  30 #ifndef S_IXUSR
  31 #define S_IXUSR 0100    /* Execute by owner.  */
  32 #endif
  33 #ifndef S_IXGRP
  34 #define S_IXGRP 0010    /* Execute by group.  */
  35 #endif
  36 #ifndef S_IXOTH
  37 #define S_IXOTH 0001    /* Execute by others.  */
  38 #endif
  39
  40 /* Counters used to initialize the bfd identifier.  */
  41
  42 static unsigned int bfd_id_counter = 0;
  43 static unsigned int bfd_reserved_id_counter = 0;
  44
  45 /*
  46 CODE_FRAGMENT
  47 .{* Set to N to open the next N BFDs using an alternate id space.  *}
  48 .extern unsigned int bfd_use_reserved_id;
  49 */
  50 unsigned int bfd_use_reserved_id = 0;
  51
  52 /* fdopen is a loser -- we should use stdio exclusively.  Unfortunately
  53    if we do that we can't use fcntl.  */
  54
  55 /* Return a new BFD.  All BFD's are allocated through this routine.  */
  56
  57 bfd *
  58 _bfd_new_bfd (void)
  59 {
  60   bfd *nbfd;
  61
  62   nbfd = (bfd *) bfd_zmalloc (sizeof (bfd));
  63   if (nbfd == NULL)
  64     return NULL;
  65
  66   if (bfd_use_reserved_id)
  67     {
  68       nbfd->id = --bfd_reserved_id_counter;
  69       --bfd_use_reserved_id;
  70     }
  71   else
  72     nbfd->id = bfd_id_counter++;
  73
  74   nbfd->memory = objalloc_create ();
  75   if (nbfd->memory == NULL)
  76     {
  77       bfd_set_error (bfd_error_no_memory);
  78       free (nbfd);
  79       return NULL;
  80     }
  81
  82   nbfd->arch_info = &bfd_default_arch_struct;
  83
  84   if (!bfd_hash_table_init_n (& nbfd->section_htab, bfd_section_hash_newfunc,
  85                               sizeof (struct section_hash_entry), 13))
  86     {
  87       free (nbfd);
  88       return NULL;
  89     }
  90
  91   return nbfd;
  92 }
  93
  94 static const struct bfd_iovec opncls_iovec;
  95
  96 /* Allocate a new BFD as a member of archive OBFD.  */
  97
  98 bfd *
  99 _bfd_new_bfd_contained_in (bfd *obfd)
 100 {
 101   bfd *nbfd;
 102
 103   nbfd = _bfd_new_bfd ();
 104   if (nbfd == NULL)
 105     return NULL;
 106   nbfd->xvec = obfd->xvec;
 107   nbfd->iovec = obfd->iovec;
 108   if (obfd->iovec == &opncls_iovec)
 109     nbfd->iostream = obfd->iostream;
 110   nbfd->my_archive = obfd;
 111   nbfd->direction = read_direction;
 112   nbfd->target_defaulted = obfd->target_defaulted;
 113   nbfd->lto_output = obfd->lto_output;
 114   nbfd->no_export = obfd->no_export;
 115   return nbfd;
 116 }
 117
 118 /* Delete a BFD.  */
 119
 120 static void
 121 _bfd_delete_bfd (bfd *abfd)
 122 {
 123   if (abfd->memory)
 124     {
 125       bfd_hash_table_free (&abfd->section_htab);
 126       objalloc_free ((struct objalloc *) abfd->memory);
 127     }
 128
 129   if (abfd->filename)
 130     free ((char *) abfd->filename);
 131   free (abfd->arelt_data);
 132   free (abfd);
 133 }
 134
 135 /* Free objalloc memory.  */
 136
 137 bfd_boolean
 138 _bfd_free_cached_info (bfd *abfd)
 139 {
 140   if (abfd->memory)
 141     {
 142       bfd_hash_table_free (&abfd->section_htab);
 143       objalloc_free ((struct objalloc *) abfd->memory);
 144
 145       abfd->sections = NULL;
 146       abfd->section_last = NULL;
 147       abfd->outsymbols = NULL;
 148       abfd->tdata.any = NULL;
 149       abfd->usrdata = NULL;
 150       abfd->memory = NULL;
 151     }
 152
 153   return TRUE;
 154 }
 155
 156 /*
 157 SECTION
 158         Opening and closing BFDs
 159
 160 SUBSECTION
 161         Functions for opening and closing
 162 */
 163
 164 /*
 165 FUNCTION
 166         bfd_fopen
 167
 168 SYNOPSIS
 169         bfd *bfd_fopen (const char *filename, const char *target,
 170                         const char *mode, int fd);
 171
 172 DESCRIPTION
 173         Open the file @var{filename} with the target @var{target}.
 174         Return a pointer to the created BFD.  If @var{fd} is not -1,
 175         then <<fdopen>> is used to open the file; otherwise, <<fopen>>
 176         is used.  @var{mode} is passed directly to <<fopen>> or
 177         <<fdopen>>.
 178
 179         Calls <<bfd_find_target>>, so @var{target} is interpreted as by
 180         that function.
 181
 182         The new BFD is marked as cacheable iff @var{fd} is -1.
 183
 184         If <<NULL>> is returned then an error has occured.   Possible errors
 185         are <<bfd_error_no_memory>>, <<bfd_error_invalid_target>> or
 186         <<system_call>> error.
 187
 188         On error, @var{fd} is always closed.
 189
 190         A copy of the @var{filename} argument is stored in the newly created
 191         BFD.  It can be accessed via the bfd_get_filename() macro.
 192 */
 193
 194 bfd *
 195 bfd_fopen (const char *filename, const char *target, const char *mode, int fd)
 196 {
 197   bfd *nbfd;
 198   const bfd_target *target_vec;
 199
 200   nbfd = _bfd_new_bfd ();
 201   if (nbfd == NULL)
 202     {
 203       if (fd != -1)
 204         close (fd);
 205       return NULL;
 206     }
 207
 208   target_vec = bfd_find_target (target, nbfd);
 209   if (target_vec == NULL)
 210     {
 211       if (fd != -1)
 212         close (fd);
 213       _bfd_delete_bfd (nbfd);
 214       return NULL;
 215     }
 216
 217 #ifdef HAVE_FDOPEN
 218   if (fd != -1)
 219     nbfd->iostream = fdopen (fd, mode);
 220   else
 221 #endif
 222     nbfd->iostream = _bfd_real_fopen (filename, mode);
 223   if (nbfd->iostream == NULL)
 224     {
 225       bfd_set_error (bfd_error_system_call);
 226       _bfd_delete_bfd (nbfd);
 227       return NULL;
 228     }
 229
 230   /* OK, put everything where it belongs.  */
 231
 232   /* PR 11983: Do not cache the original filename, but
 233      rather make a copy - the original might go away.  */
 234   nbfd->filename = xstrdup (filename);
 235
 236   /* Figure out whether the user is opening the file for reading,
 237      writing, or both, by looking at the MODE argument.  */
 238   if ((mode[0] == 'r' || mode[0] == 'w' || mode[0] == 'a')
 239       && mode[1] == '+')
 240     nbfd->direction = both_direction;
 241   else if (mode[0] == 'r')
 242     nbfd->direction = read_direction;
 243   else
 244     nbfd->direction = write_direction;
 245
 246   if (! bfd_cache_init (nbfd))
 247     {
 248       _bfd_delete_bfd (nbfd);
 249       return NULL;
 250     }
 251   nbfd->opened_once = TRUE;
 252
 253   /* If we opened the file by name, mark it cacheable; we can close it
 254      and reopen it later.  However, if a file descriptor was provided,
 255      then it may have been opened with special flags that make it
 256      unsafe to close and reopen the file.  */
 257   if (fd == -1)
 258     (void) bfd_set_cacheable (nbfd, TRUE);
 259
 260   return nbfd;
 261 }
 262
 263 /*
 264 FUNCTION
 265         bfd_openr
 266
 267 SYNOPSIS
 268         bfd *bfd_openr (const char *filename, const char *target);
 269
 270 DESCRIPTION
 271         Open the file @var{filename} (using <<fopen>>) with the target
 272         @var{target}.  Return a pointer to the created BFD.
 273
 274         Calls <<bfd_find_target>>, so @var{target} is interpreted as by
 275         that function.
 276
 277         If <<NULL>> is returned then an error has occured.   Possible errors
 278         are <<bfd_error_no_memory>>, <<bfd_error_invalid_target>> or
 279         <<system_call>> error.
 280
 281         A copy of the @var{filename} argument is stored in the newly created
 282         BFD.  It can be accessed via the bfd_get_filename() macro.
 283 */
 284
 285 bfd *
 286 bfd_openr (const char *filename, const char *target)
 287 {
 288   return bfd_fopen (filename, target, FOPEN_RB, -1);
 289 }
 290
 291 /* Don't try to `optimize' this function:
 292
 293    o - We lock using stack space so that interrupting the locking
 294        won't cause a storage leak.
 295    o - We open the file stream last, since we don't want to have to
 296        close it if anything goes wrong.  Closing the stream means closing
 297        the file descriptor too, even though we didn't open it.  */
 298 /*
 299 FUNCTION
 300         bfd_fdopenr
 301
 302 SYNOPSIS
 303         bfd *bfd_fdopenr (const char *filename, const char *target, int fd);
 304
 305 DESCRIPTION
 306         <<bfd_fdopenr>> is to <<bfd_fopenr>> much like <<fdopen>> is to
 307         <<fopen>>.  It opens a BFD on a file already described by the
 308         @var{fd} supplied.
 309
 310         When the file is later <<bfd_close>>d, the file descriptor will
 311         be closed.  If the caller desires that this file descriptor be
 312         cached by BFD (opened as needed, closed as needed to free
 313         descriptors for other opens), with the supplied @var{fd} used as
 314         an initial file descriptor (but subject to closure at any time),
 315         call bfd_set_cacheable(bfd, 1) on the returned BFD.  The default
 316         is to assume no caching; the file descriptor will remain open
 317         until <<bfd_close>>, and will not be affected by BFD operations
 318         on other files.
 319
 320         Possible errors are <<bfd_error_no_memory>>,
 321         <<bfd_error_invalid_target>> and <<bfd_error_system_call>>.
 322
 323         On error, @var{fd} is closed.
 324
 325         A copy of the @var{filename} argument is stored in the newly created
 326         BFD.  It can be accessed via the bfd_get_filename() macro.
 327 */
 328
 329 bfd *
 330 bfd_fdopenr (const char *filename, const char *target, int fd)
 331 {
 332   const char *mode;
 333 #if defined(HAVE_FCNTL) && defined(F_GETFL)
 334   int fdflags;
 335 #endif
 336
 337 #if ! defined(HAVE_FCNTL) || ! defined(F_GETFL)
 338   mode = FOPEN_RUB; /* Assume full access.  */
 339 #else
 340   fdflags = fcntl (fd, F_GETFL, NULL);
 341   if (fdflags == -1)
 342     {
 343       int save = errno;
 344
 345       close (fd);
 346       errno = save;
 347       bfd_set_error (bfd_error_system_call);
 348       return NULL;
 349     }
 350
 351   /* (O_ACCMODE) parens are to avoid Ultrix header file bug.  */
 352   switch (fdflags & (O_ACCMODE))
 353     {
 354     case O_RDONLY: mode = FOPEN_RB; break;
 355     case O_WRONLY: mode = FOPEN_RUB; break;
 356     case O_RDWR:   mode = FOPEN_RUB; break;
 357     default: abort ();
 358     }
 359 #endif
 360
 361   return bfd_fopen (filename, target, mode, fd);
 362 }
 363
 364 /*
 365 FUNCTION
 366         bfd_openstreamr
 367
 368 SYNOPSIS
 369         bfd *bfd_openstreamr (const char * filename, const char * target,
 370                               void * stream);
 371
 372 DESCRIPTION
 373         Open a BFD for read access on an existing stdio stream.  When
 374         the BFD is passed to <<bfd_close>>, the stream will be closed.
 375
 376         A copy of the @var{filename} argument is stored in the newly created
 377         BFD.  It can be accessed via the bfd_get_filename() macro.
 378 */
 379
 380 bfd *
 381 bfd_openstreamr (const char *filename, const char *target, void *streamarg)
 382 {
 383   FILE *stream = (FILE *) streamarg;
 384   bfd *nbfd;
 385   const bfd_target *target_vec;
 386
 387   nbfd = _bfd_new_bfd ();
 388   if (nbfd == NULL)
 389     return NULL;
 390
 391   target_vec = bfd_find_target (target, nbfd);
 392   if (target_vec == NULL)
 393     {
 394       _bfd_delete_bfd (nbfd);
 395       return NULL;
 396     }
 397
 398   nbfd->iostream = stream;
 399   /* PR 11983: Do not cache the original filename, but
 400      rather make a copy - the original might go away.  */
 401   nbfd->filename = xstrdup (filename);
 402   nbfd->direction = read_direction;
 403
 404   if (! bfd_cache_init (nbfd))
 405     {
 406       _bfd_delete_bfd (nbfd);
 407       return NULL;
 408     }
 409
 410   return nbfd;
 411 }
 412
 413 /*
 414 FUNCTION
 415         bfd_openr_iovec
 416
 417 SYNOPSIS
 418         bfd *bfd_openr_iovec (const char *filename, const char *target,
 419                               void *(*open_func) (struct bfd *nbfd,
 420                                                   void *open_closure),
 421                               void *open_closure,
 422                               file_ptr (*pread_func) (struct bfd *nbfd,
 423                                                       void *stream,
 424                                                       void *buf,
 425                                                       file_ptr nbytes,
 426                                                       file_ptr offset),
 427                               int (*close_func) (struct bfd *nbfd,
 428                                                  void *stream),
 429                               int (*stat_func) (struct bfd *abfd,
 430                                                 void *stream,
 431                                                 struct stat *sb));
 432
 433 DESCRIPTION
 434         Create and return a BFD backed by a read-only @var{stream}.
 435         The @var{stream} is created using @var{open_func}, accessed using
 436         @var{pread_func} and destroyed using @var{close_func}.
 437
 438         Calls <<bfd_find_target>>, so @var{target} is interpreted as by
 439         that function.
 440
 441         Calls @var{open_func} (which can call <<bfd_zalloc>> and
 442         <<bfd_get_filename>>) to obtain the read-only stream backing
 443         the BFD.  @var{open_func} either succeeds returning the
 444         non-<<NULL>> @var{stream}, or fails returning <<NULL>>
 445         (setting <<bfd_error>>).
 446
 447         Calls @var{pread_func} to request @var{nbytes} of data from
 448         @var{stream} starting at @var{offset} (e.g., via a call to
 449         <<bfd_read>>).  @var{pread_func} either succeeds returning the
 450         number of bytes read (which can be less than @var{nbytes} when
 451         end-of-file), or fails returning -1 (setting <<bfd_error>>).
 452
 453         Calls @var{close_func} when the BFD is later closed using
 454         <<bfd_close>>.  @var{close_func} either succeeds returning 0, or
 455         fails returning -1 (setting <<bfd_error>>).
 456
 457         Calls @var{stat_func} to fill in a stat structure for bfd_stat,
 458         bfd_get_size, and bfd_get_mtime calls.  @var{stat_func} returns 0
 459         on success, or returns -1 on failure (setting <<bfd_error>>).
 460
 461         If <<bfd_openr_iovec>> returns <<NULL>> then an error has
 462         occurred.  Possible errors are <<bfd_error_no_memory>>,
 463         <<bfd_error_invalid_target>> and <<bfd_error_system_call>>.
 464
 465         A copy of the @var{filename} argument is stored in the newly created
 466         BFD.  It can be accessed via the bfd_get_filename() macro.
 467 */
 468
 469 struct opncls
 470 {
 471   void *stream;
 472   file_ptr (*pread) (struct bfd *abfd, void *stream, void *buf,
 473                      file_ptr nbytes, file_ptr offset);
 474   int (*close) (struct bfd *abfd, void *stream);
 475   int (*stat) (struct bfd *abfd, void *stream, struct stat *sb);
 476   file_ptr where;
 477 };
 478
 479 static file_ptr
 480 opncls_btell (struct bfd *abfd)
 481 {
 482   struct opncls *vec = (struct opncls *) abfd->iostream;
 483   return vec->where;
 484 }
 485
 486 static int
 487 opncls_bseek (struct bfd *abfd, file_ptr offset, int whence)
 488 {
 489   struct opncls *vec = (struct opncls *) abfd->iostream;
 490   switch (whence)
 491     {
 492     case SEEK_SET: vec->where = offset; break;
 493     case SEEK_CUR: vec->where += offset; break;
 494     case SEEK_END: return -1;
 495     }
 496   return 0;
 497 }
 498
 499 static file_ptr
 500 opncls_bread (struct bfd *abfd, void *buf, file_ptr nbytes)
 501 {
 502   struct opncls *vec = (struct opncls *) abfd->iostream;
 503   file_ptr nread = (vec->pread) (abfd, vec->stream, buf, nbytes, vec->where);
 504
 505   if (nread < 0)
 506     return nread;
 507   vec->where += nread;
 508   return nread;
 509 }
 510
 511 static file_ptr
 512 opncls_bwrite (struct bfd *abfd ATTRIBUTE_UNUSED,
 513               const void *where ATTRIBUTE_UNUSED,
 514               file_ptr nbytes ATTRIBUTE_UNUSED)
 515 {
 516   return -1;
 517 }
 518
 519 static int
 520 opncls_bclose (struct bfd *abfd)
 521 {
 522   struct opncls *vec = (struct opncls *) abfd->iostream;
 523   /* Since the VEC's memory is bound to the bfd deleting the bfd will
 524      free it.  */
 525   int status = 0;
 526
 527   if (vec->close != NULL)
 528     status = (vec->close) (abfd, vec->stream);
 529   abfd->iostream = NULL;
 530   return status;
 531 }
 532
 533 static int
 534 opncls_bflush (struct bfd *abfd ATTRIBUTE_UNUSED)
 535 {
 536   return 0;
 537 }
 538
 539 static int
 540 opncls_bstat (struct bfd *abfd, struct stat *sb)
 541 {
 542   struct opncls *vec = (struct opncls *) abfd->iostream;
 543
 544   memset (sb, 0, sizeof (*sb));
 545   if (vec->stat == NULL)
 546     return 0;
 547
 548   return (vec->stat) (abfd, vec->stream, sb);
 549 }
 550
 551 static void *
 552 opncls_bmmap (struct bfd *abfd ATTRIBUTE_UNUSED,
 553               void *addr ATTRIBUTE_UNUSED,
 554               bfd_size_type len ATTRIBUTE_UNUSED,
 555               int prot ATTRIBUTE_UNUSED,
 556               int flags ATTRIBUTE_UNUSED,
 557               file_ptr offset ATTRIBUTE_UNUSED,
 558               void **map_addr ATTRIBUTE_UNUSED,
 559               bfd_size_type *map_len ATTRIBUTE_UNUSED)
 560 {
 561   return (void *) -1;
 562 }
 563
 564 static const struct bfd_iovec opncls_iovec =
 565 {
 566   &opncls_bread, &opncls_bwrite, &opncls_btell, &opncls_bseek,
 567   &opncls_bclose, &opncls_bflush, &opncls_bstat, &opncls_bmmap
 568 };
 569
 570 bfd *
 571 bfd_openr_iovec (const char *filename, const char *target,
 572                  void *(*open_p) (struct bfd *, void *),
 573                  void *open_closure,
 574                  file_ptr (*pread_p) (struct bfd *, void *, void *,
 575                                       file_ptr, file_ptr),
 576                  int (*close_p) (struct bfd *, void *),
 577                  int (*stat_p) (struct bfd *, void *, struct stat *))
 578 {
 579   bfd *nbfd;
 580   const bfd_target *target_vec;
 581   struct opncls *vec;
 582   void *stream;
 583
 584   nbfd = _bfd_new_bfd ();
 585   if (nbfd == NULL)
 586     return NULL;
 587
 588   target_vec = bfd_find_target (target, nbfd);
 589   if (target_vec == NULL)
 590     {
 591       _bfd_delete_bfd (nbfd);
 592       return NULL;
 593     }
 594
 595   /* PR 11983: Do not cache the original filename, but
 596      rather make a copy - the original might go away.  */
 597   nbfd->filename = xstrdup (filename);
 598   nbfd->direction = read_direction;
 599
 600   /* `open_p (...)' would get expanded by an the open(2) syscall macro.  */
 601   stream = (*open_p) (nbfd, open_closure);
 602   if (stream == NULL)
 603     {
 604       _bfd_delete_bfd (nbfd);
 605       return NULL;
 606     }
 607
 608   vec = (struct opncls *) bfd_zalloc (nbfd, sizeof (struct opncls));
 609   vec->stream = stream;
 610   vec->pread = pread_p;
 611   vec->close = close_p;
 612   vec->stat = stat_p;
 613
 614   nbfd->iovec = &opncls_iovec;
 615   nbfd->iostream = vec;
 616
 617   return nbfd;
 618 }
 619 \f
 620 /* bfd_openw -- open for writing.
 621    Returns a pointer to a freshly-allocated BFD on success, or NULL.
 622
 623    See comment by bfd_fdopenr before you try to modify this function.  */
 624
 625 /*
 626 FUNCTION
 627         bfd_openw
 628
 629 SYNOPSIS
 630         bfd *bfd_openw (const char *filename, const char *target);
 631
 632 DESCRIPTION
 633         Create a BFD, associated with file @var{filename}, using the
 634         file format @var{target}, and return a pointer to it.
 635
 636         Possible errors are <<bfd_error_system_call>>, <<bfd_error_no_memory>>,
 637         <<bfd_error_invalid_target>>.
 638
 639         A copy of the @var{filename} argument is stored in the newly created
 640         BFD.  It can be accessed via the bfd_get_filename() macro.
 641 */
 642
 643 bfd *
 644 bfd_openw (const char *filename, const char *target)
 645 {
 646   bfd *nbfd;
 647   const bfd_target *target_vec;
 648
 649   /* nbfd has to point to head of malloc'ed block so that bfd_close may
 650      reclaim it correctly.  */
 651   nbfd = _bfd_new_bfd ();
 652   if (nbfd == NULL)
 653     return NULL;
 654
 655   target_vec = bfd_find_target (target, nbfd);
 656   if (target_vec == NULL)
 657     {
 658       _bfd_delete_bfd (nbfd);
 659       return NULL;
 660     }
 661
 662   /* PR 11983: Do not cache the original filename, but
 663      rather make a copy - the original might go away.  */
 664   nbfd->filename = xstrdup (filename);
 665   nbfd->direction = write_direction;
 666
 667   if (bfd_open_file (nbfd) == NULL)
 668     {
 669       /* File not writeable, etc.  */
 670       bfd_set_error (bfd_error_system_call);
 671       _bfd_delete_bfd (nbfd);
 672       return NULL;
 673   }
 674
 675   return nbfd;
 676 }
 677
 678 static inline void
 679 _maybe_make_executable (bfd * abfd)
 680 {
 681   /* If the file was open for writing and is now executable,
 682      make it so.  */
 683   if (abfd->direction == write_direction
 684       && (abfd->flags & (EXEC_P | DYNAMIC)) != 0)
 685     {
 686       struct stat buf;
 687
 688       if (stat (abfd->filename, &buf) == 0
 689           /* Do not attempt to change non-regular files.  This is
 690              here especially for configure scripts and kernel builds
 691              which run tests with "ld [...] -o /dev/null".  */
 692           && S_ISREG(buf.st_mode))
 693         {
 694           unsigned int mask = umask (0);
 695
 696           umask (mask);
 697           chmod (abfd->filename,
 698                  (0777
 699                   & (buf.st_mode | ((S_IXUSR | S_IXGRP | S_IXOTH) &~ mask))));
 700         }
 701     }
 702 }
 703
 704 /*
 705 FUNCTION
 706         bfd_close
 707
 708 SYNOPSIS
 709         bfd_boolean bfd_close (bfd *abfd);
 710
 711 DESCRIPTION
 712         Close a BFD. If the BFD was open for writing, then pending
 713         operations are completed and the file written out and closed.
 714         If the created file is executable, then <<chmod>> is called
 715         to mark it as such.
 716
 717         All memory attached to the BFD is released.
 718
 719         The file descriptor associated with the BFD is closed (even
 720         if it was passed in to BFD by <<bfd_fdopenr>>).
 721
 722 RETURNS
 723         <<TRUE>> is returned if all is ok, otherwise <<FALSE>>.
 724 */
 725
 726 bfd_boolean
 727 bfd_close (bfd *abfd)
 728 {
 729   bfd_boolean ret;
 730
 731   if (bfd_write_p (abfd))
 732     {
 733       if (! BFD_SEND_FMT (abfd, _bfd_write_contents, (abfd)))
 734         return FALSE;
 735     }
 736
 737   if (! BFD_SEND (abfd, _close_and_cleanup, (abfd)))
 738     return FALSE;
 739
 740   ret = abfd->iovec->bclose (abfd) == 0;
 741
 742   if (ret)
 743     _maybe_make_executable (abfd);
 744
 745   _bfd_delete_bfd (abfd);
 746
 747   return ret;
 748 }
 749
 750 /*
 751 FUNCTION
 752         bfd_close_all_done
 753
 754 SYNOPSIS
 755         bfd_boolean bfd_close_all_done (bfd *);
 756
 757 DESCRIPTION
 758         Close a BFD.  Differs from <<bfd_close>> since it does not
 759         complete any pending operations.  This routine would be used
 760         if the application had just used BFD for swapping and didn't
 761         want to use any of the writing code.
 762
 763         If the created file is executable, then <<chmod>> is called
 764         to mark it as such.
 765
 766         All memory attached to the BFD is released.
 767
 768 RETURNS
 769         <<TRUE>> is returned if all is ok, otherwise <<FALSE>>.
 770 */
 771
 772 bfd_boolean
 773 bfd_close_all_done (bfd *abfd)
 774 {
 775   bfd_boolean ret;
 776
 777   ret = bfd_cache_close (abfd);
 778
 779   if (ret)
 780     _maybe_make_executable (abfd);
 781
 782   _bfd_delete_bfd (abfd);
 783
 784   return ret;
 785 }
 786
 787 /*
 788 FUNCTION
 789         bfd_create
 790
 791 SYNOPSIS
 792         bfd *bfd_create (const char *filename, bfd *templ);
 793
 794 DESCRIPTION
 795         Create a new BFD in the manner of <<bfd_openw>>, but without
 796         opening a file. The new BFD takes the target from the target
 797         used by @var{templ}. The format is always set to <<bfd_object>>.
 798
 799         A copy of the @var{filename} argument is stored in the newly created
 800         BFD.  It can be accessed via the bfd_get_filename() macro.
 801 */
 802
 803 bfd *
 804 bfd_create (const char *filename, bfd *templ)
 805 {
 806   bfd *nbfd;
 807
 808   nbfd = _bfd_new_bfd ();
 809   if (nbfd == NULL)
 810     return NULL;
 811   /* PR 11983: Do not cache the original filename, but
 812      rather make a copy - the original might go away.  */
 813   nbfd->filename = xstrdup (filename);
 814   if (templ)
 815     nbfd->xvec = templ->xvec;
 816   nbfd->direction = no_direction;
 817   bfd_set_format (nbfd, bfd_object);
 818
 819   return nbfd;
 820 }
 821
 822 /*
 823 FUNCTION
 824         bfd_make_writable
 825
 826 SYNOPSIS
 827         bfd_boolean bfd_make_writable (bfd *abfd);
 828
 829 DESCRIPTION
 830         Takes a BFD as created by <<bfd_create>> and converts it
 831         into one like as returned by <<bfd_openw>>.  It does this
 832         by converting the BFD to BFD_IN_MEMORY.  It's assumed that
 833         you will call <<bfd_make_readable>> on this bfd later.
 834
 835 RETURNS
 836         <<TRUE>> is returned if all is ok, otherwise <<FALSE>>.
 837 */
 838
 839 bfd_boolean
 840 bfd_make_writable (bfd *abfd)
 841 {
 842   struct bfd_in_memory *bim;
 843
 844   if (abfd->direction != no_direction)
 845     {
 846       bfd_set_error (bfd_error_invalid_operation);
 847       return FALSE;
 848     }
 849
 850   bim = (struct bfd_in_memory *) bfd_malloc (sizeof (struct bfd_in_memory));
 851   if (bim == NULL)
 852     return FALSE;       /* bfd_error already set.  */
 853   abfd->iostream = bim;
 854   /* bfd_bwrite will grow these as needed.  */
 855   bim->size = 0;
 856   bim->buffer = 0;
 857
 858   abfd->flags |= BFD_IN_MEMORY;
 859   abfd->iovec = &_bfd_memory_iovec;
 860   abfd->origin = 0;
 861   abfd->direction = write_direction;
 862   abfd->where = 0;
 863
 864   return TRUE;
 865 }
 866
 867 /*
 868 FUNCTION
 869         bfd_make_readable
 870
 871 SYNOPSIS
 872         bfd_boolean bfd_make_readable (bfd *abfd);
 873
 874 DESCRIPTION
 875         Takes a BFD as created by <<bfd_create>> and
 876         <<bfd_make_writable>> and converts it into one like as
 877         returned by <<bfd_openr>>.  It does this by writing the
 878         contents out to the memory buffer, then reversing the
 879         direction.
 880
 881 RETURNS
 882         <<TRUE>> is returned if all is ok, otherwise <<FALSE>>.  */
 883
 884 bfd_boolean
 885 bfd_make_readable (bfd *abfd)
 886 {
 887   if (abfd->direction != write_direction || !(abfd->flags & BFD_IN_MEMORY))
 888     {
 889       bfd_set_error (bfd_error_invalid_operation);
 890       return FALSE;
 891     }
 892
 893   if (! BFD_SEND_FMT (abfd, _bfd_write_contents, (abfd)))
 894     return FALSE;
 895
 896   if (! BFD_SEND (abfd, _close_and_cleanup, (abfd)))
 897     return FALSE;
 898
 899   abfd->arch_info = &bfd_default_arch_struct;
 900
 901   abfd->where = 0;
 902   abfd->format = bfd_unknown;
 903   abfd->my_archive = NULL;
 904   abfd->origin = 0;
 905   abfd->opened_once = FALSE;
 906   abfd->output_has_begun = FALSE;
 907   abfd->section_count = 0;
 908   abfd->usrdata = NULL;
 909   abfd->cacheable = FALSE;
 910   abfd->flags |= BFD_IN_MEMORY;
 911   abfd->mtime_set = FALSE;
 912
 913   abfd->target_defaulted = TRUE;
 914   abfd->direction = read_direction;
 915   abfd->sections = 0;
 916   abfd->symcount = 0;
 917   abfd->outsymbols = 0;
 918   abfd->tdata.any = 0;
 919
 920   bfd_section_list_clear (abfd);
 921   bfd_check_format (abfd, bfd_object);
 922
 923   return TRUE;
 924 }
 925
 926 /*
 927 FUNCTION
 928         bfd_alloc
 929
 930 SYNOPSIS
 931         void *bfd_alloc (bfd *abfd, bfd_size_type wanted);
 932
 933 DESCRIPTION
 934         Allocate a block of @var{wanted} bytes of memory attached to
 935         <<abfd>> and return a pointer to it.
 936 */
 937
 938 void *
 939 bfd_alloc (bfd *abfd, bfd_size_type size)
 940 {
 941   void *ret;
 942   unsigned long ul_size = (unsigned long) size;
 943
 944   if (size != ul_size
 945       /* Note - although objalloc_alloc takes an unsigned long as its
 946          argument, internally the size is treated as a signed long.  This can
 947          lead to problems where, for example, a request to allocate -1 bytes
 948          can result in just 1 byte being allocated, rather than
 949          ((unsigned long) -1) bytes.  Also memory checkers will often
 950          complain about attempts to allocate a negative amount of memory.
 951          So to stop these problems we fail if the size is negative.  */
 952       || ((signed long) ul_size) < 0)
 953     {
 954       bfd_set_error (bfd_error_no_memory);
 955       return NULL;
 956     }
 957
 958   ret = objalloc_alloc ((struct objalloc *) abfd->memory, ul_size);
 959   if (ret == NULL)
 960     bfd_set_error (bfd_error_no_memory);
 961   return ret;
 962 }
 963
 964 /*
 965 INTERNAL_FUNCTION
 966         bfd_alloc2
 967
 968 SYNOPSIS
 969         void *bfd_alloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size);
 970
 971 DESCRIPTION
 972         Allocate a block of @var{nmemb} elements of @var{size} bytes each
 973         of memory attached to <<abfd>> and return a pointer to it.
 974 */
 975
 976 void *
 977 bfd_alloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size)
 978 {
 979   if ((nmemb | size) >= HALF_BFD_SIZE_TYPE
 980       && size != 0
 981       && nmemb > ~(bfd_size_type) 0 / size)
 982     {
 983       bfd_set_error (bfd_error_no_memory);
 984       return NULL;
 985     }
 986
 987   return bfd_alloc (abfd, size * nmemb);
 988 }
 989
 990 /*
 991 FUNCTION
 992         bfd_zalloc
 993
 994 SYNOPSIS
 995         void *bfd_zalloc (bfd *abfd, bfd_size_type wanted);
 996
 997 DESCRIPTION
 998         Allocate a block of @var{wanted} bytes of zeroed memory
 999         attached to <<abfd>> and return a pointer to it.
1000 */
1001
1002 void *
1003 bfd_zalloc (bfd *abfd, bfd_size_type size)
1004 {
1005   void *res;
1006
1007   res = bfd_alloc (abfd, size);
1008   if (res)
1009     memset (res, 0, (size_t) size);
1010   return res;
1011 }
1012
1013 /*
1014 INTERNAL_FUNCTION
1015         bfd_zalloc2
1016
1017 SYNOPSIS
1018         void *bfd_zalloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size);
1019
1020 DESCRIPTION
1021         Allocate a block of @var{nmemb} elements of @var{size} bytes each
1022         of zeroed memory attached to <<abfd>> and return a pointer to it.
1023 */
1024
1025 void *
1026 bfd_zalloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size)
1027 {
1028   void *res;
1029
1030   if ((nmemb | size) >= HALF_BFD_SIZE_TYPE
1031       && size != 0
1032       && nmemb > ~(bfd_size_type) 0 / size)
1033     {
1034       bfd_set_error (bfd_error_no_memory);
1035       return NULL;
1036     }
1037
1038   size *= nmemb;
1039
1040   res = bfd_alloc (abfd, size);
1041   if (res)
1042     memset (res, 0, (size_t) size);
1043   return res;
1044 }
1045
1046 /* Free a block allocated for a BFD.
1047    Note:  Also frees all more recently allocated blocks!  */
1048
1049 void
1050 bfd_release (bfd *abfd, void *block)
1051 {
1052   objalloc_free_block ((struct objalloc *) abfd->memory, block);
1053 }
1054
1055
1056 /*
1057    GNU Extension: separate debug-info files
1058
1059    The idea here is that a special section called .gnu_debuglink might be
1060    embedded in a binary file, which indicates that some *other* file
1061    contains the real debugging information. This special section contains a
1062    filename and CRC32 checksum, which we read and resolve to another file,
1063    if it exists.
1064
1065    This facilitates "optional" provision of debugging information, without
1066    having to provide two complete copies of every binary object (with and
1067    without debug symbols).  */
1068
1069 #define GNU_DEBUGLINK           ".gnu_debuglink"
1070 #define GNU_DEBUGALTLINK        ".gnu_debugaltlink"
1071
1072 /*
1073 FUNCTION
1074         bfd_calc_gnu_debuglink_crc32
1075
1076 SYNOPSIS
1077         unsigned long bfd_calc_gnu_debuglink_crc32
1078           (unsigned long crc, const unsigned char *buf, bfd_size_type len);
1079
1080 DESCRIPTION
1081         Computes a CRC value as used in the .gnu_debuglink section.
1082         Advances the previously computed @var{crc} value by computing
1083         and adding in the crc32 for @var{len} bytes of @var{buf}.
1084
1085 RETURNS
1086         Return the updated CRC32 value.
1087 */
1088
1089 unsigned long
1090 bfd_calc_gnu_debuglink_crc32 (unsigned long crc,
1091                               const unsigned char *buf,
1092                               bfd_size_type len)
1093 {
1094   static const unsigned long crc32_table[256] =
1095     {
1096       0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419,
1097       0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4,
1098       0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07,
1099       0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de,
1100       0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856,
1101       0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9,
1102       0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4,
1103       0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b,
1104       0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3,
1105       0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a,
1106       0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599,
1107       0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924,
1108       0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190,
1109       0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f,
1110       0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e,
1111       0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01,
1112       0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed,
1113       0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950,
1114       0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3,
1115       0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2,
1116       0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a,
1117       0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5,
1118       0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010,
1119       0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f,
1120       0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17,
1121       0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6,
1122       0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615,
1123       0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8,
1124       0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344,
1125       0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb,
1126       0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a,
1127       0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5,
1128       0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1,
1129       0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c,
1130       0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef,
1131       0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236,
1132       0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe,
1133       0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31,
1134       0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c,
1135       0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713,
1136       0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b,
1137       0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242,
1138       0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1,
1139       0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c,
1140       0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278,
1141       0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7,
1142       0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66,
1143       0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9,
1144       0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605,
1145       0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8,
1146       0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b,
1147       0x2d02ef8d
1148     };
1149   const unsigned char *end;
1150
1151   crc = ~crc & 0xffffffff;
1152   for (end = buf + len; buf < end; ++ buf)
1153     crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8);
1154   return ~crc & 0xffffffff;
1155 }
1156
1157
1158 /*
1159 INTERNAL_FUNCTION
1160         bfd_get_debug_link_info_1
1161
1162 SYNOPSIS
1163         char *bfd_get_debug_link_info_1 (bfd *abfd, void *crc32_out);
1164
1165 DESCRIPTION
1166         Extracts the filename and CRC32 value for any separate debug
1167         information file associated with @var{abfd}.
1168
1169         The @var{crc32_out} parameter is an untyped pointer because
1170         this routine is used as a @code{get_func_type} function, but it
1171         is expected to be an unsigned long pointer.
1172
1173 RETURNS
1174         The filename of the associated debug information file, or NULL
1175         if there is no such file.  If the filename was found then the
1176         contents of @var{crc32_out} are updated to hold the corresponding
1177         CRC32 value for the file.
1178
1179         The returned filename is allocated with @code{malloc}; freeing
1180         it is the responsibility of the caller.
1181 */
1182
1183 static char *
1184 bfd_get_debug_link_info_1 (bfd *abfd, void *crc32_out)
1185 {
1186   asection *sect;
1187   unsigned long *crc32 = (unsigned long *) crc32_out;
1188   bfd_byte *contents;
1189   unsigned int crc_offset;
1190   char *name;
1191
1192   BFD_ASSERT (abfd);
1193   BFD_ASSERT (crc32_out);
1194
1195   sect = bfd_get_section_by_name (abfd, GNU_DEBUGLINK);
1196
1197   if (sect == NULL)
1198     return NULL;
1199
1200   if (!bfd_malloc_and_get_section (abfd, sect, &contents))
1201     {
1202       if (contents != NULL)
1203         free (contents);
1204       return NULL;
1205     }
1206
1207   /* CRC value is stored after the filename, aligned up to 4 bytes.  */
1208   name = (char *) contents;
1209   /* PR 17597: avoid reading off the end of the buffer.  */
1210   crc_offset = strnlen (name, bfd_get_section_size (sect)) + 1;
1211   crc_offset = (crc_offset + 3) & ~3;
1212   if (crc_offset >= bfd_get_section_size (sect))
1213     return NULL;
1214
1215   *crc32 = bfd_get_32 (abfd, contents + crc_offset);
1216   return name;
1217 }
1218
1219
1220 /*
1221 FUNCTION
1222         bfd_get_debug_link_info
1223
1224 SYNOPSIS
1225         char *bfd_get_debug_link_info (bfd *abfd, unsigned long *crc32_out);
1226
1227 DESCRIPTION
1228         Extracts the filename and CRC32 value for any separate debug
1229         information file associated with @var{abfd}.
1230
1231 RETURNS
1232         The filename of the associated debug information file, or NULL
1233         if there is no such file.  If the filename was found then the
1234         contents of @var{crc32_out} are updated to hold the corresponding
1235         CRC32 value for the file.
1236
1237         The returned filename is allocated with @code{malloc}; freeing
1238         it is the responsibility of the caller.
1239 */
1240
1241 char *
1242 bfd_get_debug_link_info (bfd *abfd, unsigned long *crc32_out)
1243 {
1244   return bfd_get_debug_link_info_1 (abfd, crc32_out);
1245 }
1246
1247 /*
1248 FUNCTION
1249         bfd_get_alt_debug_link_info
1250
1251 SYNOPSIS
1252         char *bfd_get_alt_debug_link_info (bfd * abfd,
1253                                            bfd_size_type *buildid_len,
1254                                            bfd_byte **buildid_out);
1255
1256 DESCRIPTION
1257         Fetch the filename and BuildID value for any alternate debuginfo
1258         associated with @var{abfd}.  Return NULL if no such info found,
1259         otherwise return filename and update @var{buildid_len} and
1260         @var{buildid_out}.  The returned filename and build_id are
1261         allocated with @code{malloc}; freeing them is the responsibility
1262         of the caller.
1263 */
1264
1265 char *
1266 bfd_get_alt_debug_link_info (bfd * abfd, bfd_size_type *buildid_len,
1267                              bfd_byte **buildid_out)
1268 {
1269   asection *sect;
1270   bfd_byte *contents;
1271   unsigned int buildid_offset;
1272   char *name;
1273
1274   BFD_ASSERT (abfd);
1275   BFD_ASSERT (buildid_len);
1276   BFD_ASSERT (buildid_out);
1277
1278   sect = bfd_get_section_by_name (abfd, GNU_DEBUGALTLINK);
1279
1280   if (sect == NULL)
1281     return NULL;
1282
1283   if (!bfd_malloc_and_get_section (abfd, sect, & contents))
1284     {
1285       if (contents != NULL)
1286         free (contents);
1287       return NULL;
1288     }
1289
1290   /* BuildID value is stored after the filename.  */
1291   name = (char *) contents;
1292   buildid_offset = strnlen (name, bfd_get_section_size (sect)) + 1;
1293   if (buildid_offset >= bfd_get_section_size (sect))
1294     return NULL;
1295
1296   *buildid_len = bfd_get_section_size (sect) - buildid_offset;
1297   *buildid_out = bfd_malloc (*buildid_len);
1298   memcpy (*buildid_out, contents + buildid_offset, *buildid_len);
1299
1300   return name;
1301 }
1302
1303 /*
1304 INTERNAL_FUNCTION
1305         separate_debug_file_exists
1306
1307 SYNOPSIS
1308         bfd_boolean separate_debug_file_exists
1309           (char *name, void *crc32_p);
1310
1311 DESCRIPTION
1312         Checks to see if @var{name} is a file and if its contents
1313         match @var{crc32}, which is a pointer to an @code{unsigned
1314         long} containing a CRC32.
1315
1316         The @var{crc32_p} parameter is an untyped pointer because
1317         this routine is used as a @code{check_func_type} function.
1318 */
1319
1320 static bfd_boolean
1321 separate_debug_file_exists (const char *name, void *crc32_p)
1322 {
1323   static unsigned char buffer [8 * 1024];
1324   unsigned long file_crc = 0;
1325   FILE *f;
1326   bfd_size_type count;
1327   unsigned long crc;
1328
1329   BFD_ASSERT (name);
1330   BFD_ASSERT (crc32_p);
1331
1332   crc = *(unsigned long *) crc32_p;
1333
1334   f = _bfd_real_fopen (name, FOPEN_RB);
1335   if (f == NULL)
1336     return FALSE;
1337
1338   while ((count = fread (buffer, 1, sizeof (buffer), f)) > 0)
1339     file_crc = bfd_calc_gnu_debuglink_crc32 (file_crc, buffer, count);
1340
1341   fclose (f);
1342
1343   return crc == file_crc;
1344 }
1345
1346 /*
1347 INTERNAL_FUNCTION
1348         separate_alt_debug_file_exists
1349
1350 SYNOPSIS
1351         bfd_boolean separate_alt_debug_file_exists
1352           (char *name, void *unused);
1353
1354 DESCRIPTION
1355         Checks to see if @var{name} is a file.
1356 */
1357
1358 static bfd_boolean
1359 separate_alt_debug_file_exists (const char *name, void *unused ATTRIBUTE_UNUSED)
1360 {
1361   FILE *f;
1362
1363   BFD_ASSERT (name);
1364
1365   f = _bfd_real_fopen (name, FOPEN_RB);
1366   if (f == NULL)
1367     return FALSE;
1368
1369   fclose (f);
1370
1371   return TRUE;
1372 }
1373
1374 /*
1375 INTERNAL_FUNCTION
1376         find_separate_debug_file
1377
1378 SYNOPSIS
1379         char *find_separate_debug_file
1380           (bfd *abfd, const char *dir, bfd_boolean include_dirs,
1381            get_func_type get, check_func_type check, void *data);
1382
1383 DESCRIPTION
1384         Searches for a debug information file corresponding to @var{abfd}.
1385
1386         The name of the separate debug info file is returned by the
1387         @var{get} function.  This function scans various fixed locations
1388         in the filesystem, including the file tree rooted at @var{dir}.
1389         If the @var{include_dirs} parameter is true then the directory
1390         components of @var{abfd}'s filename will be included in the
1391         searched locations.
1392
1393         @var{data} is passed unmodified to the @var{get} and @var{check}
1394         functions.  It is generally used to implement build-id-like
1395         matching in the callback functions.
1396
1397 RETURNS
1398         Returns the filename of the first file to be found which
1399         receives a TRUE result from the @var{check} function.
1400         Returns NULL if no valid file could be found.
1401 */
1402
1403 typedef char *      (* get_func_type) (bfd *, void *);
1404 typedef bfd_boolean (* check_func_type) (const char *, void *);
1405
1406 static char *
1407 find_separate_debug_file (bfd *           abfd,
1408                           const char *    debug_file_directory,
1409                           bfd_boolean     include_dirs,
1410                           get_func_type   get_func,
1411                           check_func_type check_func,
1412                           void *          func_data)
1413 {
1414   char *base;
1415   char *dir;
1416   char *debugfile;
1417   char *canon_dir;
1418   size_t dirlen;
1419   size_t canon_dirlen;
1420
1421   BFD_ASSERT (abfd);
1422   if (debug_file_directory == NULL)
1423     debug_file_directory = ".";
1424
1425   /* BFD may have been opened from a stream.  */
1426   if (abfd->filename == NULL)
1427     {
1428       bfd_set_error (bfd_error_invalid_operation);
1429       return NULL;
1430     }
1431
1432   base = get_func (abfd, func_data);
1433
1434   if (base == NULL)
1435     return NULL;
1436
1437   if (base[0] == '\0')
1438     {
1439       free (base);
1440       bfd_set_error (bfd_error_no_debug_section);
1441       return NULL;
1442     }
1443
1444   if (include_dirs)
1445     {
1446       for (dirlen = strlen (abfd->filename); dirlen > 0; dirlen--)
1447         if (IS_DIR_SEPARATOR (abfd->filename[dirlen - 1]))
1448           break;
1449
1450       dir = (char *) bfd_malloc (dirlen + 1);
1451       if (dir == NULL)
1452         {
1453           free (base);
1454           return NULL;
1455         }
1456       memcpy (dir, abfd->filename, dirlen);
1457       dir[dirlen] = '\0';
1458     }
1459   else
1460     {
1461       dir = (char *) bfd_malloc (1);
1462       * dir = 0;
1463       dirlen = 0;
1464     }
1465
1466   /* Compute the canonical name of the bfd object with all symbolic links
1467      resolved, for use in the global debugfile directory.  */
1468   canon_dir = lrealpath (abfd->filename);
1469   for (canon_dirlen = strlen (canon_dir); canon_dirlen > 0; canon_dirlen--)
1470     if (IS_DIR_SEPARATOR (canon_dir[canon_dirlen - 1]))
1471       break;
1472   canon_dir[canon_dirlen] = '\0';
1473
1474 #ifndef EXTRA_DEBUG_ROOT1
1475 #define EXTRA_DEBUG_ROOT1 "/usr/lib/debug"
1476 #endif
1477 #ifndef EXTRA_DEBUG_ROOT2
1478 #define EXTRA_DEBUG_ROOT2 "/usr/lib/debug/usr"
1479 #endif
1480
1481   debugfile = (char *)
1482       bfd_malloc (strlen (debug_file_directory) + 1
1483                   + (canon_dirlen > dirlen ? canon_dirlen : dirlen)
1484                   + strlen (".debug/")
1485 #ifdef EXTRA_DEBUG_ROOT1
1486                   + strlen (EXTRA_DEBUG_ROOT1)
1487 #endif
1488 #ifdef EXTRA_DEBUG_ROOT2
1489                   + strlen (EXTRA_DEBUG_ROOT2)
1490 #endif
1491                   + strlen (base)
1492                   + 1);
1493   if (debugfile == NULL)
1494     goto found; /* Actually this returns NULL.  */
1495
1496   /* First try in the same directory as the original file.
1497
1498      FIXME: Strictly speaking if we are using the build-id method,
1499      (ie include_dirs == FALSE) then we should only check absolute
1500      paths, not relative ones like this one (and the next one).
1501      The check is left in however as this allows the binutils
1502      testsuite to exercise this feature without having to install
1503      a file into the root filesystem.  (See binutils/testsuite/
1504      binutils-all/objdump.exp for the test).  */
1505   sprintf (debugfile, "%s%s", dir, base);
1506   if (check_func (debugfile, func_data))
1507     goto found;
1508
1509   /* Then try in a subdirectory called .debug.  */
1510   sprintf (debugfile, "%s.debug/%s", dir, base);
1511   if (check_func (debugfile, func_data))
1512     goto found;
1513
1514 #ifdef EXTRA_DEBUG_ROOT1
1515   /* Try the first extra debug file root.  */
1516   sprintf (debugfile, "%s%s%s", EXTRA_DEBUG_ROOT1,
1517            include_dirs ? canon_dir : "/", base);
1518   if (check_func (debugfile, func_data))
1519     goto found;
1520 #endif
1521
1522 #ifdef EXTRA_DEBUG_ROOT2
1523   /* Try the second extra debug file root.  */
1524   sprintf (debugfile, "%s%s%s", EXTRA_DEBUG_ROOT2,
1525            include_dirs ? canon_dir : "/", base);
1526   if (check_func (debugfile, func_data))
1527     goto found;
1528 #endif
1529
1530   /* Then try in the global debugfile directory.  */
1531   strcpy (debugfile, debug_file_directory);
1532   dirlen = strlen (debug_file_directory) - 1;
1533   if (include_dirs)
1534     {
1535       if (dirlen > 0
1536           && debug_file_directory[dirlen] != '/'
1537           && canon_dir[0] != '/')
1538         strcat (debugfile, "/");
1539       strcat (debugfile, canon_dir);
1540     }
1541   else
1542     {
1543       if (dirlen > 0 && debug_file_directory[dirlen] != '/')
1544         strcat (debugfile, "/");
1545     }
1546   strcat (debugfile, base);
1547
1548   if (check_func (debugfile, func_data))
1549     goto found;
1550
1551   /* Failed to find the file.  */
1552   free (debugfile);
1553   debugfile = NULL;
1554
1555  found:
1556   free (base);
1557   free (dir);
1558   free (canon_dir);
1559   return debugfile;
1560 }
1561
1562 /*
1563 FUNCTION
1564         bfd_follow_gnu_debuglink
1565
1566 SYNOPSIS
1567         char *bfd_follow_gnu_debuglink (bfd *abfd, const char *dir);
1568
1569 DESCRIPTION
1570         Takes a BFD and searches it for a .gnu_debuglink section.  If this
1571         section is found, it examines the section for the name and checksum
1572         of a '.debug' file containing auxiliary debugging information.  It
1573         then searches the filesystem for this .debug file in some standard
1574         locations, including the directory tree rooted at @var{dir}, and if
1575         found returns the full filename.
1576
1577         If @var{dir} is NULL, the search will take place starting at
1578         the current directory.
1579
1580 RETURNS
1581         <<NULL>> on any errors or failure to locate the .debug file,
1582         otherwise a pointer to a heap-allocated string containing the
1583         filename.  The caller is responsible for freeing this string.
1584 */
1585
1586 char *
1587 bfd_follow_gnu_debuglink (bfd *abfd, const char *dir)
1588 {
1589   unsigned long crc32;
1590
1591   return find_separate_debug_file (abfd, dir, TRUE,
1592                                    bfd_get_debug_link_info_1,
1593                                    separate_debug_file_exists, &crc32);
1594 }
1595
1596 /* Helper for bfd_follow_gnu_debugaltlink.  It just returns the name
1597    of the separate debug file.  */
1598
1599 static char *
1600 get_alt_debug_link_info_shim (bfd * abfd, void *unused ATTRIBUTE_UNUSED)
1601 {
1602   bfd_size_type len;
1603   bfd_byte *buildid = NULL;
1604   char *result = bfd_get_alt_debug_link_info (abfd, &len, &buildid);
1605
1606   free (buildid);
1607
1608   return result;
1609 }
1610
1611 /*
1612 FUNCTION
1613         bfd_follow_gnu_debugaltlink
1614
1615 SYNOPSIS
1616         char *bfd_follow_gnu_debugaltlink (bfd *abfd, const char *dir);
1617
1618 DESCRIPTION
1619         Takes a BFD and searches it for a .gnu_debugaltlink section.  If this
1620         section is found, it examines the section for the name of a file
1621         containing auxiliary debugging information.  It then searches the
1622         filesystem for this file in a set of standard locations, including
1623         the directory tree rooted at @var{dir}, and if found returns the
1624         full filename.
1625
1626         If @var{dir} is NULL, the search will take place starting at
1627         the current directory.
1628
1629 RETURNS
1630         <<NULL>> on any errors or failure to locate the debug file,
1631         otherwise a pointer to a heap-allocated string containing the
1632         filename.  The caller is responsible for freeing this string.
1633 */
1634
1635 char *
1636 bfd_follow_gnu_debugaltlink (bfd *abfd, const char *dir)
1637 {
1638   return find_separate_debug_file (abfd, dir, TRUE,
1639                                    get_alt_debug_link_info_shim,
1640                                    separate_alt_debug_file_exists,
1641                                    NULL);
1642 }
1643
1644 /*
1645 FUNCTION
1646         bfd_create_gnu_debuglink_section
1647
1648 SYNOPSIS
1649         struct bfd_section *bfd_create_gnu_debuglink_section
1650           (bfd *abfd, const char *filename);
1651
1652 DESCRIPTION
1653         Takes a @var{BFD} and adds a .gnu_debuglink section to it.  The
1654         section is sized to be big enough to contain a link to the specified
1655         @var{filename}.
1656
1657 RETURNS
1658         A pointer to the new section is returned if all is ok.  Otherwise
1659         <<NULL>> is returned and bfd_error is set.
1660 */
1661
1662 asection *
1663 bfd_create_gnu_debuglink_section (bfd *abfd, const char *filename)
1664 {
1665   asection *sect;
1666   bfd_size_type debuglink_size;
1667   flagword flags;
1668
1669   if (abfd == NULL || filename == NULL)
1670     {
1671       bfd_set_error (bfd_error_invalid_operation);
1672       return NULL;
1673     }
1674
1675   /* Strip off any path components in filename.  */
1676   filename = lbasename (filename);
1677
1678   sect = bfd_get_section_by_name (abfd, GNU_DEBUGLINK);
1679   if (sect)
1680     {
1681       /* Section already exists.  */
1682       bfd_set_error (bfd_error_invalid_operation);
1683       return NULL;
1684     }
1685
1686   flags = SEC_HAS_CONTENTS | SEC_READONLY | SEC_DEBUGGING;
1687   sect = bfd_make_section_with_flags (abfd, GNU_DEBUGLINK, flags);
1688   if (sect == NULL)
1689     return NULL;
1690
1691   /* Compute the size of the section.  Allow for the CRC after the filename,
1692      and padding so that it will start on a 4-byte boundary.  */
1693   debuglink_size = strlen (filename) + 1;
1694   debuglink_size += 3;
1695   debuglink_size &= ~3;
1696   debuglink_size += 4;
1697
1698   if (! bfd_set_section_size (abfd, sect, debuglink_size))
1699     /* XXX Should we delete the section from the bfd ?  */
1700     return NULL;
1701
1702   /* PR 21193: Ensure that the section has 4-byte alignment for the CRC.
1703      Note - despite the name of the function being called, we are
1704      setting an alignment power, not a byte alignment value.  */
1705   bfd_set_section_alignment (abfd, sect, 2);
1706
1707   return sect;
1708 }
1709
1710
1711 /*
1712 FUNCTION
1713         bfd_fill_in_gnu_debuglink_section
1714
1715 SYNOPSIS
1716         bfd_boolean bfd_fill_in_gnu_debuglink_section
1717           (bfd *abfd, struct bfd_section *sect, const char *filename);
1718
1719 DESCRIPTION
1720         Takes a @var{BFD} and containing a .gnu_debuglink section @var{SECT}
1721         and fills in the contents of the section to contain a link to the
1722         specified @var{filename}.  The filename should be relative to the
1723         current directory.
1724
1725 RETURNS
1726         <<TRUE>> is returned if all is ok.  Otherwise <<FALSE>> is returned
1727         and bfd_error is set.
1728 */
1729
1730 bfd_boolean
1731 bfd_fill_in_gnu_debuglink_section (bfd *abfd,
1732                                    struct bfd_section *sect,
1733                                    const char *filename)
1734 {
1735   bfd_size_type debuglink_size;
1736   unsigned long crc32;
1737   char * contents;
1738   bfd_size_type crc_offset;
1739   FILE * handle;
1740   static unsigned char buffer[8 * 1024];
1741   size_t count;
1742   size_t filelen;
1743
1744   if (abfd == NULL || sect == NULL || filename == NULL)
1745     {
1746       bfd_set_error (bfd_error_invalid_operation);
1747       return FALSE;
1748     }
1749
1750   /* Make sure that we can read the file.
1751      XXX - Should we attempt to locate the debug info file using the same
1752      algorithm as gdb ?  At the moment, since we are creating the
1753      .gnu_debuglink section, we insist upon the user providing us with a
1754      correct-for-section-creation-time path, but this need not conform to
1755      the gdb location algorithm.  */
1756   handle = _bfd_real_fopen (filename, FOPEN_RB);
1757   if (handle == NULL)
1758     {
1759       bfd_set_error (bfd_error_system_call);
1760       return FALSE;
1761     }
1762
1763   crc32 = 0;
1764   while ((count = fread (buffer, 1, sizeof buffer, handle)) > 0)
1765     crc32 = bfd_calc_gnu_debuglink_crc32 (crc32, buffer, count);
1766   fclose (handle);
1767
1768   /* Strip off any path components in filename,
1769      now that we no longer need them.  */
1770   filename = lbasename (filename);
1771
1772   filelen = strlen (filename);
1773   debuglink_size = filelen + 1;
1774   debuglink_size += 3;
1775   debuglink_size &= ~3;
1776   debuglink_size += 4;
1777
1778   contents = (char *) bfd_malloc (debuglink_size);
1779   if (contents == NULL)
1780     {
1781       /* XXX Should we delete the section from the bfd ?  */
1782       return FALSE;
1783     }
1784
1785   crc_offset = debuglink_size - 4;
1786   memcpy (contents, filename, filelen);
1787   memset (contents + filelen, 0, crc_offset - filelen);
1788
1789   bfd_put_32 (abfd, crc32, contents + crc_offset);
1790
1791   if (! bfd_set_section_contents (abfd, sect, contents, 0, debuglink_size))
1792     {
1793       /* XXX Should we delete the section from the bfd ?  */
1794       free (contents);
1795       return FALSE;
1796     }
1797
1798   return TRUE;
1799 }
1800
1801 /*
1802 INTERNAL_FUNCTION
1803         get_build_id
1804
1805 SYNOPSIS
1806         struct bfd_build_id * get_build_id (bfd *abfd);
1807
1808 DESCRIPTION
1809         Finds the build-id associated with @var{abfd}.  If the build-id is
1810         extracted from the note section then a build-id structure is built
1811         for it, using memory allocated to @var{abfd}, and this is then
1812         attached to the @var{abfd}.
1813
1814 RETURNS
1815         Returns a pointer to the build-id structure if a build-id could be
1816         found.  If no build-id is found NULL is returned and error code is
1817         set.
1818 */
1819
1820 static struct bfd_build_id *
1821 get_build_id (bfd *abfd)
1822 {
1823   struct bfd_build_id *build_id;
1824   Elf_Internal_Note inote;
1825   Elf_External_Note *enote;
1826   bfd_byte *contents;
1827   asection *sect;
1828
1829   BFD_ASSERT (abfd);
1830
1831   if (abfd->build_id && abfd->build_id->size > 0)
1832     /* Save some time by using the already computed build-id.  */
1833     return (struct bfd_build_id *) abfd->build_id;
1834
1835   sect = bfd_get_section_by_name (abfd, ".note.gnu.build-id");
1836   if (sect == NULL)
1837     {
1838       bfd_set_error (bfd_error_no_debug_section);
1839       return NULL;
1840     }
1841
1842   /* FIXME: Should we support smaller build-id notes ?  */
1843   if (bfd_get_section_size (sect) < 0x24)
1844     {
1845       bfd_set_error (bfd_error_invalid_operation);
1846       return NULL;
1847     }
1848
1849   if (!bfd_malloc_and_get_section (abfd, sect, & contents))
1850     {
1851       if (contents != NULL)
1852         free (contents);
1853       return NULL;
1854     }
1855
1856   enote = (Elf_External_Note *) contents;
1857   inote.type = H_GET_32 (abfd, enote->type);
1858   inote.namesz = H_GET_32 (abfd, enote->namesz);
1859   inote.namedata = enote->name;
1860   inote.descsz = H_GET_32 (abfd, enote->descsz);
1861   inote.descdata = inote.namedata + BFD_ALIGN (inote.namesz, 4);
1862   /* FIXME: Should we check for extra notes in this section ?  */
1863
1864   if (inote.descsz == 0
1865       || inote.type != NT_GNU_BUILD_ID
1866       || inote.namesz != 4 /* sizeof "GNU"  */
1867       || strcmp (inote.namedata, "GNU") != 0)
1868     {
1869       free (contents);
1870       bfd_set_error (bfd_error_invalid_operation);
1871       return NULL;
1872     }
1873
1874   build_id = bfd_alloc (abfd, sizeof (struct bfd_build_id) + inote.descsz);
1875   if (build_id == NULL)
1876     {
1877       free (contents);
1878       return NULL;
1879     }
1880
1881   build_id->size = inote.descsz;
1882   memcpy (build_id->data, inote.descdata, inote.descsz);
1883   abfd->build_id = build_id;
1884   free (contents);
1885
1886   return build_id;
1887 }
1888
1889 /*
1890 INTERNAL_FUNCTION
1891         get_build_id_name
1892
1893 SYNOPSIS
1894         char * get_build_id_name (bfd *abfd, void *build_id_out_p)
1895
1896 DESCRIPTION
1897         Searches @var{abfd} for a build-id, and then constructs a pathname
1898         from it.  The path is computed as .build-id/NN/NN+NN.debug where
1899         NNNN+NN is the build-id value as a hexadecimal string.
1900
1901 RETURNS
1902         Returns the constructed filename or NULL upon error.
1903         It is the caller's responsibility to free the memory used to hold the
1904         filename.
1905         If a filename is returned then the @var{build_id_out_p}
1906         parameter (which points to a @code{struct bfd_build_id}
1907         pointer) is set to a pointer to the build_id structure.
1908 */
1909
1910 static char *
1911 get_build_id_name (bfd *abfd, void *build_id_out_p)
1912 {
1913   struct bfd_build_id **build_id_out = build_id_out_p;
1914   struct bfd_build_id *build_id;
1915   char *name;
1916   char *n;
1917   bfd_size_type s;
1918   bfd_byte *d;
1919
1920   if (abfd == NULL || abfd->filename == NULL || build_id_out == NULL)
1921     {
1922       bfd_set_error (bfd_error_invalid_operation);
1923       return NULL;
1924     }
1925
1926   build_id = get_build_id (abfd);
1927   if (build_id == NULL)
1928     return NULL;
1929
1930   /* Compute the debug pathname corresponding to the build-id.  */
1931   name = bfd_malloc (strlen (".build-id/") + build_id->size * 2 + 2 + strlen (".debug"));
1932   if (name == NULL)
1933     {
1934       bfd_set_error (bfd_error_no_memory);
1935       return NULL;
1936     }
1937   n = name;
1938   d = build_id->data;
1939   s = build_id->size;
1940
1941   n += sprintf (n, ".build-id/");
1942   n += sprintf (n, "%02x", (unsigned) *d++); s--;
1943   n += sprintf (n, "/");
1944   while (s--)
1945     n += sprintf (n, "%02x", (unsigned) *d++);
1946   n += sprintf (n, ".debug");
1947
1948   *build_id_out = build_id;
1949   return name;
1950 }
1951
1952 /*
1953 INTERNAL_FUNCTION
1954         check_build_id_file
1955
1956 SYNOPSIS
1957         bfd_boolean check_build_id_file (char *name, void *buildid_p);
1958
1959 DESCRIPTION
1960         Checks to see if @var{name} is a readable file and if its build-id
1961         matches @var{buildid}.
1962
1963 RETURNS
1964         Returns TRUE if the file exists, is readable, and contains a
1965         build-id which matches the build-id pointed at by
1966         @var{build_id_p} (which is really a @code{struct bfd_build_id **}).
1967 */
1968
1969 static bfd_boolean
1970 check_build_id_file (const char *name, void *buildid_p)
1971 {
1972   struct bfd_build_id *orig_build_id;
1973   struct bfd_build_id *build_id;
1974   bfd * file;
1975   bfd_boolean result;
1976
1977   BFD_ASSERT (name);
1978   BFD_ASSERT (buildid_p);
1979
1980   file = bfd_openr (name, NULL);
1981   if (file == NULL)
1982     return FALSE;
1983
1984   /* If the file is an archive, process all of its elements.  */
1985   if (! bfd_check_format (file, bfd_object))
1986     {
1987       bfd_close (file);
1988       return FALSE;
1989     }
1990
1991   build_id = get_build_id (file);
1992   if (build_id == NULL)
1993     {
1994       bfd_close (file);
1995       return FALSE;
1996     }
1997
1998   orig_build_id = *(struct bfd_build_id **) buildid_p;
1999
2000   result = build_id->size == orig_build_id->size
2001     && memcmp (build_id->data, orig_build_id->data, build_id->size) == 0;
2002
2003   (void) bfd_close (file);
2004
2005   return result;
2006 }
2007
2008 /*
2009 FUNCTION
2010         bfd_follow_build_id_debuglink
2011
2012 SYNOPSIS
2013         char *bfd_follow_build_id_debuglink (bfd *abfd, const char *dir);
2014
2015 DESCRIPTION
2016         Takes @var{abfd} and searches it for a .note.gnu.build-id section.
2017         If this section is found, it extracts the value of the NT_GNU_BUILD_ID
2018         note, which should be a hexadecimal value @var{NNNN+NN} (for
2019         32+ hex digits).  It then searches the filesystem for a file named
2020         @var{.build-id/NN/NN+NN.debug} in a set of standard locations,
2021         including the directory tree rooted at @var{dir}.  The filename
2022         of the first matching file to be found is returned.  A matching
2023         file should contain a .note.gnu.build-id section with the same
2024         @var{NNNN+NN} note as @var{abfd}, although this check is currently
2025         not implemented.
2026
2027         If @var{dir} is NULL, the search will take place starting at
2028         the current directory.
2029
2030 RETURNS
2031         <<NULL>> on any errors or failure to locate the debug file,
2032         otherwise a pointer to a heap-allocated string containing the
2033         filename.  The caller is responsible for freeing this string.
2034 */
2035
2036 char *
2037 bfd_follow_build_id_debuglink (bfd *abfd, const char *dir)
2038 {
2039   struct bfd_build_id *build_id;
2040
2041   return find_separate_debug_file (abfd, dir, FALSE,
2042                                    get_build_id_name,
2043                                    check_build_id_file, &build_id);
2044 }