bfd/opncls.c

   1 /* opncls.c -- open and close a BFD.
   2    Copyright 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000,
   3    2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
   4    Free Software Foundation, Inc.
   5
   6    Written by Cygnus Support.
   7
   8    This file is part of BFD, the Binary File Descriptor library.
   9
  10    This program is free software; you can redistribute it and/or modify
  11    it under the terms of the GNU General Public License as published by
  12    the Free Software Foundation; either version 3 of the License, or
  13    (at your option) any later version.
  14
  15    This program is distributed in the hope that it will be useful,
  16    but WITHOUT ANY WARRANTY; without even the implied warranty of
  17    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18    GNU General Public License for more details.
  19
  20    You should have received a copy of the GNU General Public License
  21    along with this program; if not, write to the Free Software
  22    Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston,
  23    MA 02110-1301, USA.  */
  24
  25 #include "sysdep.h"
  26 #include "bfd.h"
  27 #include "objalloc.h"
  28 #include "libbfd.h"
  29 #include "libiberty.h"
  30
  31 #ifndef S_IXUSR
  32 #define S_IXUSR 0100    /* Execute by owner.  */
  33 #endif
  34 #ifndef S_IXGRP
  35 #define S_IXGRP 0010    /* Execute by group.  */
  36 #endif
  37 #ifndef S_IXOTH
  38 #define S_IXOTH 0001    /* Execute by others.  */
  39 #endif
  40
  41 /* Counter used to initialize the bfd identifier.  */
  42
  43 static unsigned int _bfd_id_counter = 0;
  44
  45 /* fdopen is a loser -- we should use stdio exclusively.  Unfortunately
  46    if we do that we can't use fcntl.  */
  47
  48 /* Return a new BFD.  All BFD's are allocated through this routine.  */
  49
  50 bfd *
  51 _bfd_new_bfd (void)
  52 {
  53   bfd *nbfd;
  54
  55   nbfd = bfd_zmalloc (sizeof (bfd));
  56   if (nbfd == NULL)
  57     return NULL;
  58
  59   nbfd->id = _bfd_id_counter++;
  60
  61   nbfd->memory = objalloc_create ();
  62   if (nbfd->memory == NULL)
  63     {
  64       bfd_set_error (bfd_error_no_memory);
  65       free (nbfd);
  66       return NULL;
  67     }
  68
  69   nbfd->arch_info = &bfd_default_arch_struct;
  70
  71   nbfd->direction = no_direction;
  72   nbfd->iostream = NULL;
  73   nbfd->where = 0;
  74   if (!bfd_hash_table_init_n (& nbfd->section_htab, bfd_section_hash_newfunc,
  75                               sizeof (struct section_hash_entry), 251))
  76     {
  77       free (nbfd);
  78       return NULL;
  79     }
  80   nbfd->sections = NULL;
  81   nbfd->section_last = NULL;
  82   nbfd->format = bfd_unknown;
  83   nbfd->my_archive = NULL;
  84   nbfd->origin = 0;
  85   nbfd->opened_once = FALSE;
  86   nbfd->output_has_begun = FALSE;
  87   nbfd->section_count = 0;
  88   nbfd->usrdata = NULL;
  89   nbfd->cacheable = FALSE;
  90   nbfd->flags = BFD_NO_FLAGS;
  91   nbfd->mtime_set = FALSE;
  92
  93   return nbfd;
  94 }
  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   nbfd->my_archive = obfd;
 109   nbfd->direction = read_direction;
 110   nbfd->target_defaulted = obfd->target_defaulted;
 111   return nbfd;
 112 }
 113
 114 /* Delete a BFD.  */
 115
 116 void
 117 _bfd_delete_bfd (bfd *abfd)
 118 {
 119   if (abfd->memory)
 120     {
 121       bfd_hash_table_free (&abfd->section_htab);
 122       objalloc_free ((struct objalloc *) abfd->memory);
 123     }
 124   free (abfd);
 125 }
 126
 127 /* Free objalloc memory.  */
 128
 129 bfd_boolean
 130 _bfd_free_cached_info (bfd *abfd)
 131 {
 132   if (abfd->memory)
 133     {
 134       bfd_hash_table_free (&abfd->section_htab);
 135       objalloc_free ((struct objalloc *) abfd->memory);
 136
 137       abfd->sections = NULL;
 138       abfd->section_last = NULL;
 139       abfd->outsymbols = NULL;
 140       abfd->tdata.any = NULL;
 141       abfd->usrdata = NULL;
 142       abfd->memory = NULL;
 143     }
 144
 145   return TRUE;
 146 }
 147
 148 /*
 149 SECTION
 150         Opening and closing BFDs
 151
 152 SUBSECTION
 153         Functions for opening and closing
 154 */
 155
 156 /*
 157 FUNCTION
 158         bfd_fopen
 159
 160 SYNOPSIS
 161         bfd *bfd_fopen (const char *filename, const char *target,
 162                         const char *mode, int fd);
 163
 164 DESCRIPTION
 165         Open the file @var{filename} with the target @var{target}.
 166         Return a pointer to the created BFD.  If @var{fd} is not -1,
 167         then <<fdopen>> is used to open the file; otherwise, <<fopen>>
 168         is used.  @var{mode} is passed directly to <<fopen>> or
 169         <<fdopen>>.
 170
 171         Calls <<bfd_find_target>>, so @var{target} is interpreted as by
 172         that function.
 173
 174         The new BFD is marked as cacheable iff @var{fd} is -1.
 175
 176         If <<NULL>> is returned then an error has occured.   Possible errors
 177         are <<bfd_error_no_memory>>, <<bfd_error_invalid_target>> or
 178         <<system_call>> error.
 179 */
 180
 181 bfd *
 182 bfd_fopen (const char *filename, const char *target, const char *mode, int fd)
 183 {
 184   bfd *nbfd;
 185   const bfd_target *target_vec;
 186
 187   nbfd = _bfd_new_bfd ();
 188   if (nbfd == NULL)
 189     return NULL;
 190
 191   target_vec = bfd_find_target (target, nbfd);
 192   if (target_vec == NULL)
 193     {
 194       _bfd_delete_bfd (nbfd);
 195       return NULL;
 196     }
 197
 198 #ifdef HAVE_FDOPEN
 199   if (fd != -1)
 200     nbfd->iostream = fdopen (fd, mode);
 201   else
 202 #endif
 203     nbfd->iostream = real_fopen (filename, mode);
 204   if (nbfd->iostream == NULL)
 205     {
 206       bfd_set_error (bfd_error_system_call);
 207       _bfd_delete_bfd (nbfd);
 208       return NULL;
 209     }
 210
 211   /* OK, put everything where it belongs.  */
 212   nbfd->filename = filename;
 213
 214   /* Figure out whether the user is opening the file for reading,
 215      writing, or both, by looking at the MODE argument.  */
 216   if ((mode[0] == 'r' || mode[0] == 'w' || mode[0] == 'a')
 217       && mode[1] == '+')
 218     nbfd->direction = both_direction;
 219   else if (mode[0] == 'r')
 220     nbfd->direction = read_direction;
 221   else
 222     nbfd->direction = write_direction;
 223
 224   if (! bfd_cache_init (nbfd))
 225     {
 226       _bfd_delete_bfd (nbfd);
 227       return NULL;
 228     }
 229   nbfd->opened_once = TRUE;
 230   /* If we opened the file by name, mark it cacheable; we can close it
 231      and reopen it later.  However, if a file descriptor was provided,
 232      then it may have been opened with special flags that make it
 233      unsafe to close and reopen the file.  */
 234   if (fd == -1)
 235     bfd_set_cacheable (nbfd, TRUE);
 236
 237   return nbfd;
 238 }
 239
 240 /*
 241 FUNCTION
 242         bfd_openr
 243
 244 SYNOPSIS
 245         bfd *bfd_openr (const char *filename, const char *target);
 246
 247 DESCRIPTION
 248         Open the file @var{filename} (using <<fopen>>) with the target
 249         @var{target}.  Return a pointer to the created BFD.
 250
 251         Calls <<bfd_find_target>>, so @var{target} is interpreted as by
 252         that function.
 253
 254         If <<NULL>> is returned then an error has occured.   Possible errors
 255         are <<bfd_error_no_memory>>, <<bfd_error_invalid_target>> or
 256         <<system_call>> error.
 257 */
 258
 259 bfd *
 260 bfd_openr (const char *filename, const char *target)
 261 {
 262   return bfd_fopen (filename, target, FOPEN_RB, -1);
 263 }
 264
 265 /* Don't try to `optimize' this function:
 266
 267    o - We lock using stack space so that interrupting the locking
 268        won't cause a storage leak.
 269    o - We open the file stream last, since we don't want to have to
 270        close it if anything goes wrong.  Closing the stream means closing
 271        the file descriptor too, even though we didn't open it.  */
 272 /*
 273 FUNCTION
 274         bfd_fdopenr
 275
 276 SYNOPSIS
 277         bfd *bfd_fdopenr (const char *filename, const char *target, int fd);
 278
 279 DESCRIPTION
 280         <<bfd_fdopenr>> is to <<bfd_fopenr>> much like <<fdopen>> is to
 281         <<fopen>>.  It opens a BFD on a file already described by the
 282         @var{fd} supplied.
 283
 284         When the file is later <<bfd_close>>d, the file descriptor will
 285         be closed.  If the caller desires that this file descriptor be
 286         cached by BFD (opened as needed, closed as needed to free
 287         descriptors for other opens), with the supplied @var{fd} used as
 288         an initial file descriptor (but subject to closure at any time),
 289         call bfd_set_cacheable(bfd, 1) on the returned BFD.  The default
 290         is to assume no caching; the file descriptor will remain open
 291         until <<bfd_close>>, and will not be affected by BFD operations
 292         on other files.
 293
 294         Possible errors are <<bfd_error_no_memory>>,
 295         <<bfd_error_invalid_target>> and <<bfd_error_system_call>>.
 296 */
 297
 298 bfd *
 299 bfd_fdopenr (const char *filename, const char *target, int fd)
 300 {
 301   const char *mode;
 302 #if defined(HAVE_FCNTL) && defined(F_GETFL)
 303   int fdflags;
 304 #endif
 305
 306 #if ! defined(HAVE_FCNTL) || ! defined(F_GETFL)
 307   mode = FOPEN_RUB; /* Assume full access.  */
 308 #else
 309   fdflags = fcntl (fd, F_GETFL, NULL);
 310   if (fdflags == -1)
 311     {
 312       bfd_set_error (bfd_error_system_call);
 313       return NULL;
 314     }
 315
 316   /* (O_ACCMODE) parens are to avoid Ultrix header file bug.  */
 317   switch (fdflags & (O_ACCMODE))
 318     {
 319     case O_RDONLY: mode = FOPEN_RB; break;
 320     case O_WRONLY: mode = FOPEN_RUB; break;
 321     case O_RDWR:   mode = FOPEN_RUB; break;
 322     default: abort ();
 323     }
 324 #endif
 325
 326   return bfd_fopen (filename, target, mode, fd);
 327 }
 328
 329 /*
 330 FUNCTION
 331         bfd_openstreamr
 332
 333 SYNOPSIS
 334         bfd *bfd_openstreamr (const char *, const char *, void *);
 335
 336 DESCRIPTION
 337
 338         Open a BFD for read access on an existing stdio stream.  When
 339         the BFD is passed to <<bfd_close>>, the stream will be closed.
 340 */
 341
 342 bfd *
 343 bfd_openstreamr (const char *filename, const char *target, void *streamarg)
 344 {
 345   FILE *stream = streamarg;
 346   bfd *nbfd;
 347   const bfd_target *target_vec;
 348
 349   nbfd = _bfd_new_bfd ();
 350   if (nbfd == NULL)
 351     return NULL;
 352
 353   target_vec = bfd_find_target (target, nbfd);
 354   if (target_vec == NULL)
 355     {
 356       _bfd_delete_bfd (nbfd);
 357       return NULL;
 358     }
 359
 360   nbfd->iostream = stream;
 361   nbfd->filename = filename;
 362   nbfd->direction = read_direction;
 363
 364   if (! bfd_cache_init (nbfd))
 365     {
 366       _bfd_delete_bfd (nbfd);
 367       return NULL;
 368     }
 369
 370   return nbfd;
 371 }
 372
 373 /*
 374 FUNCTION
 375         bfd_openr_iovec
 376
 377 SYNOPSIS
 378         bfd *bfd_openr_iovec (const char *filename, const char *target,
 379                               void *(*open) (struct bfd *nbfd,
 380                                              void *open_closure),
 381                               void *open_closure,
 382                               file_ptr (*pread) (struct bfd *nbfd,
 383                                                  void *stream,
 384                                                  void *buf,
 385                                                  file_ptr nbytes,
 386                                                  file_ptr offset),
 387                               int (*close) (struct bfd *nbfd,
 388                                             void *stream),
 389                               int (*stat) (struct bfd *abfd,
 390                                            void *stream,
 391                                            struct stat *sb));
 392
 393 DESCRIPTION
 394
 395         Create and return a BFD backed by a read-only @var{stream}.
 396         The @var{stream} is created using @var{open}, accessed using
 397         @var{pread} and destroyed using @var{close}.
 398
 399         Calls <<bfd_find_target>>, so @var{target} is interpreted as by
 400         that function.
 401
 402         Calls @var{open} (which can call <<bfd_zalloc>> and
 403         <<bfd_get_filename>>) to obtain the read-only stream backing
 404         the BFD.  @var{open} either succeeds returning the
 405         non-<<NULL>> @var{stream}, or fails returning <<NULL>>
 406         (setting <<bfd_error>>).
 407
 408         Calls @var{pread} to request @var{nbytes} of data from
 409         @var{stream} starting at @var{offset} (e.g., via a call to
 410         <<bfd_read>>).  @var{pread} either succeeds returning the
 411         number of bytes read (which can be less than @var{nbytes} when
 412         end-of-file), or fails returning -1 (setting <<bfd_error>>).
 413
 414         Calls @var{close} when the BFD is later closed using
 415         <<bfd_close>>.  @var{close} either succeeds returning 0, or
 416         fails returning -1 (setting <<bfd_error>>).
 417
 418         Calls @var{stat} to fill in a stat structure for bfd_stat,
 419         bfd_get_size, and bfd_get_mtime calls.  @var{stat} returns 0
 420         on success, or returns -1 on failure (setting <<bfd_error>>).
 421
 422         If <<bfd_openr_iovec>> returns <<NULL>> then an error has
 423         occurred.  Possible errors are <<bfd_error_no_memory>>,
 424         <<bfd_error_invalid_target>> and <<bfd_error_system_call>>.
 425
 426 */
 427
 428 struct opncls
 429 {
 430   void *stream;
 431   file_ptr (*pread) (struct bfd *abfd, void *stream, void *buf,
 432                      file_ptr nbytes, file_ptr offset);
 433   int (*close) (struct bfd *abfd, void *stream);
 434   int (*stat) (struct bfd *abfd, void *stream, struct stat *sb);
 435   file_ptr where;
 436 };
 437
 438 static file_ptr
 439 opncls_btell (struct bfd *abfd)
 440 {
 441   struct opncls *vec = abfd->iostream;
 442   return vec->where;
 443 }
 444
 445 static int
 446 opncls_bseek (struct bfd *abfd, file_ptr offset, int whence)
 447 {
 448   struct opncls *vec = abfd->iostream;
 449   switch (whence)
 450     {
 451     case SEEK_SET: vec->where = offset; break;
 452     case SEEK_CUR: vec->where += offset; break;
 453     case SEEK_END: return -1;
 454     }
 455   return 0;
 456 }
 457
 458 static file_ptr
 459 opncls_bread (struct bfd *abfd, void *buf, file_ptr nbytes)
 460 {
 461   struct opncls *vec = abfd->iostream;
 462   file_ptr nread = (vec->pread) (abfd, vec->stream, buf, nbytes, vec->where);
 463   if (nread < 0)
 464     return nread;
 465   vec->where += nread;
 466   return nread;
 467 }
 468
 469 static file_ptr
 470 opncls_bwrite (struct bfd *abfd ATTRIBUTE_UNUSED,
 471               const void *where ATTRIBUTE_UNUSED,
 472               file_ptr nbytes ATTRIBUTE_UNUSED)
 473 {
 474   return -1;
 475 }
 476
 477 static int
 478 opncls_bclose (struct bfd *abfd)
 479 {
 480   struct opncls *vec = abfd->iostream;
 481   /* Since the VEC's memory is bound to the bfd deleting the bfd will
 482      free it.  */
 483   int status = 0;
 484   if (vec->close != NULL)
 485     status = (vec->close) (abfd, vec->stream);
 486   abfd->iostream = NULL;
 487   return status;
 488 }
 489
 490 static int
 491 opncls_bflush (struct bfd *abfd ATTRIBUTE_UNUSED)
 492 {
 493   return 0;
 494 }
 495
 496 static int
 497 opncls_bstat (struct bfd *abfd, struct stat *sb)
 498 {
 499   struct opncls *vec = abfd->iostream;
 500
 501   memset (sb, 0, sizeof (*sb));
 502   if (vec->stat == NULL)
 503     return 0;
 504
 505   return (vec->stat) (abfd, vec->stream, sb);
 506 }
 507
 508 static void *
 509 opncls_bmmap (struct bfd *abfd ATTRIBUTE_UNUSED,
 510               void *addr ATTRIBUTE_UNUSED,
 511               bfd_size_type len ATTRIBUTE_UNUSED,
 512               int prot ATTRIBUTE_UNUSED,
 513               int flags ATTRIBUTE_UNUSED,
 514               file_ptr offset ATTRIBUTE_UNUSED)
 515 {
 516   return (void *) -1;
 517 }
 518
 519 static const struct bfd_iovec opncls_iovec = {
 520   &opncls_bread, &opncls_bwrite, &opncls_btell, &opncls_bseek,
 521   &opncls_bclose, &opncls_bflush, &opncls_bstat, &opncls_bmmap
 522 };
 523
 524 bfd *
 525 bfd_openr_iovec (const char *filename, const char *target,
 526                  void *(*open) (struct bfd *nbfd,
 527                                 void *open_closure),
 528                  void *open_closure,
 529                  file_ptr (*pread) (struct bfd *abfd,
 530                                     void *stream,
 531                                     void *buf,
 532                                     file_ptr nbytes,
 533                                     file_ptr offset),
 534                  int (*close) (struct bfd *nbfd,
 535                                void *stream),
 536                  int (*stat) (struct bfd *abfd,
 537                               void *stream,
 538                               struct stat *sb))
 539 {
 540   bfd *nbfd;
 541   const bfd_target *target_vec;
 542   struct opncls *vec;
 543   void *stream;
 544
 545   nbfd = _bfd_new_bfd ();
 546   if (nbfd == NULL)
 547     return NULL;
 548
 549   target_vec = bfd_find_target (target, nbfd);
 550   if (target_vec == NULL)
 551     {
 552       _bfd_delete_bfd (nbfd);
 553       return NULL;
 554     }
 555
 556   nbfd->filename = filename;
 557   nbfd->direction = read_direction;
 558
 559   /* `open (...)' would get expanded by an the open(2) syscall macro.  */
 560   stream = (*open) (nbfd, open_closure);
 561   if (stream == NULL)
 562     {
 563       _bfd_delete_bfd (nbfd);
 564       return NULL;
 565     }
 566
 567   vec = bfd_zalloc (nbfd, sizeof (struct opncls));
 568   vec->stream = stream;
 569   vec->pread = pread;
 570   vec->close = close;
 571   vec->stat = stat;
 572
 573   nbfd->iovec = &opncls_iovec;
 574   nbfd->iostream = vec;
 575
 576   return nbfd;
 577 }
 578 \f
 579 /* bfd_openw -- open for writing.
 580    Returns a pointer to a freshly-allocated BFD on success, or NULL.
 581
 582    See comment by bfd_fdopenr before you try to modify this function.  */
 583
 584 /*
 585 FUNCTION
 586         bfd_openw
 587
 588 SYNOPSIS
 589         bfd *bfd_openw (const char *filename, const char *target);
 590
 591 DESCRIPTION
 592         Create a BFD, associated with file @var{filename}, using the
 593         file format @var{target}, and return a pointer to it.
 594
 595         Possible errors are <<bfd_error_system_call>>, <<bfd_error_no_memory>>,
 596         <<bfd_error_invalid_target>>.
 597 */
 598
 599 bfd *
 600 bfd_openw (const char *filename, const char *target)
 601 {
 602   bfd *nbfd;
 603   const bfd_target *target_vec;
 604
 605   /* nbfd has to point to head of malloc'ed block so that bfd_close may
 606      reclaim it correctly.  */
 607   nbfd = _bfd_new_bfd ();
 608   if (nbfd == NULL)
 609     return NULL;
 610
 611   target_vec = bfd_find_target (target, nbfd);
 612   if (target_vec == NULL)
 613     {
 614       _bfd_delete_bfd (nbfd);
 615       return NULL;
 616     }
 617
 618   nbfd->filename = filename;
 619   nbfd->direction = write_direction;
 620
 621   if (bfd_open_file (nbfd) == NULL)
 622     {
 623       /* File not writeable, etc.  */
 624       bfd_set_error (bfd_error_system_call);
 625       _bfd_delete_bfd (nbfd);
 626       return NULL;
 627   }
 628
 629   return nbfd;
 630 }
 631
 632 static inline void
 633 _maybe_make_executable (bfd * abfd)
 634 {
 635   /* If the file was open for writing and is now executable,
 636      make it so.  */
 637   if (abfd->direction == write_direction
 638       && abfd->flags & EXEC_P)
 639     {
 640       struct stat buf;
 641
 642       if (stat (abfd->filename, &buf) == 0
 643           /* Do not attempt to change non-regular files.  This is
 644              here especially for configure scripts and kernel builds
 645              which run tests with "ld [...] -o /dev/null".  */
 646           && S_ISREG(buf.st_mode))
 647         {
 648           unsigned int mask = umask (0);
 649
 650           umask (mask);
 651           chmod (abfd->filename,
 652                  (0777
 653                   & (buf.st_mode | ((S_IXUSR | S_IXGRP | S_IXOTH) &~ mask))));
 654         }
 655     }
 656 }
 657
 658 /*
 659
 660 FUNCTION
 661         bfd_close
 662
 663 SYNOPSIS
 664         bfd_boolean bfd_close (bfd *abfd);
 665
 666 DESCRIPTION
 667
 668         Close a BFD. If the BFD was open for writing, then pending
 669         operations are completed and the file written out and closed.
 670         If the created file is executable, then <<chmod>> is called
 671         to mark it as such.
 672
 673         All memory attached to the BFD is released.
 674
 675         The file descriptor associated with the BFD is closed (even
 676         if it was passed in to BFD by <<bfd_fdopenr>>).
 677
 678 RETURNS
 679         <<TRUE>> is returned if all is ok, otherwise <<FALSE>>.
 680 */
 681
 682
 683 bfd_boolean
 684 bfd_close (bfd *abfd)
 685 {
 686   bfd_boolean ret;
 687   bfd *nbfd;
 688   bfd *next;
 689
 690   if (bfd_write_p (abfd))
 691     {
 692       if (! BFD_SEND_FMT (abfd, _bfd_write_contents, (abfd)))
 693         return FALSE;
 694     }
 695
 696   /* Close nested archives (if this bfd is a thin archive).  */
 697   for (nbfd = abfd->nested_archives; nbfd; nbfd = next)
 698     {
 699       next = nbfd->archive_next;
 700       bfd_close (nbfd);
 701     }
 702
 703   if (! BFD_SEND (abfd, _close_and_cleanup, (abfd)))
 704     return FALSE;
 705
 706   /* FIXME: cagney/2004-02-15: Need to implement a BFD_IN_MEMORY io
 707      vector.  */
 708   if (!(abfd->flags & BFD_IN_MEMORY))
 709     ret = abfd->iovec->bclose (abfd);
 710   else
 711     ret = TRUE;
 712
 713   if (ret)
 714     _maybe_make_executable (abfd);
 715
 716   _bfd_delete_bfd (abfd);
 717
 718   return ret;
 719 }
 720
 721 /*
 722 FUNCTION
 723         bfd_close_all_done
 724
 725 SYNOPSIS
 726         bfd_boolean bfd_close_all_done (bfd *);
 727
 728 DESCRIPTION
 729         Close a BFD.  Differs from <<bfd_close>> since it does not
 730         complete any pending operations.  This routine would be used
 731         if the application had just used BFD for swapping and didn't
 732         want to use any of the writing code.
 733
 734         If the created file is executable, then <<chmod>> is called
 735         to mark it as such.
 736
 737         All memory attached to the BFD is released.
 738
 739 RETURNS
 740         <<TRUE>> is returned if all is ok, otherwise <<FALSE>>.
 741 */
 742
 743 bfd_boolean
 744 bfd_close_all_done (bfd *abfd)
 745 {
 746   bfd_boolean ret;
 747
 748   ret = bfd_cache_close (abfd);
 749
 750   if (ret)
 751     _maybe_make_executable (abfd);
 752
 753   _bfd_delete_bfd (abfd);
 754
 755   return ret;
 756 }
 757
 758 /*
 759 FUNCTION
 760         bfd_create
 761
 762 SYNOPSIS
 763         bfd *bfd_create (const char *filename, bfd *templ);
 764
 765 DESCRIPTION
 766         Create a new BFD in the manner of <<bfd_openw>>, but without
 767         opening a file. The new BFD takes the target from the target
 768         used by @var{template}. The format is always set to <<bfd_object>>.
 769 */
 770
 771 bfd *
 772 bfd_create (const char *filename, bfd *templ)
 773 {
 774   bfd *nbfd;
 775
 776   nbfd = _bfd_new_bfd ();
 777   if (nbfd == NULL)
 778     return NULL;
 779   nbfd->filename = filename;
 780   if (templ)
 781     nbfd->xvec = templ->xvec;
 782   nbfd->direction = no_direction;
 783   bfd_set_format (nbfd, bfd_object);
 784
 785   return nbfd;
 786 }
 787
 788 /*
 789 FUNCTION
 790         bfd_make_writable
 791
 792 SYNOPSIS
 793         bfd_boolean bfd_make_writable (bfd *abfd);
 794
 795 DESCRIPTION
 796         Takes a BFD as created by <<bfd_create>> and converts it
 797         into one like as returned by <<bfd_openw>>.  It does this
 798         by converting the BFD to BFD_IN_MEMORY.  It's assumed that
 799         you will call <<bfd_make_readable>> on this bfd later.
 800
 801 RETURNS
 802         <<TRUE>> is returned if all is ok, otherwise <<FALSE>>.
 803 */
 804
 805 bfd_boolean
 806 bfd_make_writable (bfd *abfd)
 807 {
 808   struct bfd_in_memory *bim;
 809
 810   if (abfd->direction != no_direction)
 811     {
 812       bfd_set_error (bfd_error_invalid_operation);
 813       return FALSE;
 814     }
 815
 816   bim = bfd_malloc (sizeof (struct bfd_in_memory));
 817   if (bim == NULL)
 818     return FALSE;       /* bfd_error already set.  */
 819   abfd->iostream = bim;
 820   /* bfd_bwrite will grow these as needed.  */
 821   bim->size = 0;
 822   bim->buffer = 0;
 823
 824   abfd->flags |= BFD_IN_MEMORY;
 825   abfd->direction = write_direction;
 826   abfd->where = 0;
 827
 828   return TRUE;
 829 }
 830
 831 /*
 832 FUNCTION
 833         bfd_make_readable
 834
 835 SYNOPSIS
 836         bfd_boolean bfd_make_readable (bfd *abfd);
 837
 838 DESCRIPTION
 839         Takes a BFD as created by <<bfd_create>> and
 840         <<bfd_make_writable>> and converts it into one like as
 841         returned by <<bfd_openr>>.  It does this by writing the
 842         contents out to the memory buffer, then reversing the
 843         direction.
 844
 845 RETURNS
 846         <<TRUE>> is returned if all is ok, otherwise <<FALSE>>.  */
 847
 848 bfd_boolean
 849 bfd_make_readable (bfd *abfd)
 850 {
 851   if (abfd->direction != write_direction || !(abfd->flags & BFD_IN_MEMORY))
 852     {
 853       bfd_set_error (bfd_error_invalid_operation);
 854       return FALSE;
 855     }
 856
 857   if (! BFD_SEND_FMT (abfd, _bfd_write_contents, (abfd)))
 858     return FALSE;
 859
 860   if (! BFD_SEND (abfd, _close_and_cleanup, (abfd)))
 861     return FALSE;
 862
 863
 864   abfd->arch_info = &bfd_default_arch_struct;
 865
 866   abfd->where = 0;
 867   abfd->format = bfd_unknown;
 868   abfd->my_archive = NULL;
 869   abfd->origin = 0;
 870   abfd->opened_once = FALSE;
 871   abfd->output_has_begun = FALSE;
 872   abfd->section_count = 0;
 873   abfd->usrdata = NULL;
 874   abfd->cacheable = FALSE;
 875   abfd->flags = BFD_IN_MEMORY;
 876   abfd->mtime_set = FALSE;
 877
 878   abfd->target_defaulted = TRUE;
 879   abfd->direction = read_direction;
 880   abfd->sections = 0;
 881   abfd->symcount = 0;
 882   abfd->outsymbols = 0;
 883   abfd->tdata.any = 0;
 884
 885   bfd_section_list_clear (abfd);
 886   bfd_check_format (abfd, bfd_object);
 887
 888   return TRUE;
 889 }
 890
 891 /*
 892 INTERNAL_FUNCTION
 893         bfd_alloc
 894
 895 SYNOPSIS
 896         void *bfd_alloc (bfd *abfd, bfd_size_type wanted);
 897
 898 DESCRIPTION
 899         Allocate a block of @var{wanted} bytes of memory attached to
 900         <<abfd>> and return a pointer to it.
 901 */
 902
 903 void *
 904 bfd_alloc (bfd *abfd, bfd_size_type size)
 905 {
 906   void *ret;
 907
 908   if (size != (unsigned long) size)
 909     {
 910       bfd_set_error (bfd_error_no_memory);
 911       return NULL;
 912     }
 913
 914   ret = objalloc_alloc (abfd->memory, (unsigned long) size);
 915   if (ret == NULL)
 916     bfd_set_error (bfd_error_no_memory);
 917   return ret;
 918 }
 919
 920 /*
 921 INTERNAL_FUNCTION
 922         bfd_alloc2
 923
 924 SYNOPSIS
 925         void *bfd_alloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size);
 926
 927 DESCRIPTION
 928         Allocate a block of @var{nmemb} elements of @var{size} bytes each
 929         of memory attached to <<abfd>> and return a pointer to it.
 930 */
 931
 932 void *
 933 bfd_alloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size)
 934 {
 935   void *ret;
 936
 937   if ((nmemb | size) >= HALF_BFD_SIZE_TYPE
 938       && size != 0
 939       && nmemb > ~(bfd_size_type) 0 / size)
 940     {
 941       bfd_set_error (bfd_error_no_memory);
 942       return NULL;
 943     }
 944
 945   size *= nmemb;
 946
 947   if (size != (unsigned long) size)
 948     {
 949       bfd_set_error (bfd_error_no_memory);
 950       return NULL;
 951     }
 952
 953   ret = objalloc_alloc (abfd->memory, (unsigned long) size);
 954   if (ret == NULL)
 955     bfd_set_error (bfd_error_no_memory);
 956   return ret;
 957 }
 958
 959 /*
 960 INTERNAL_FUNCTION
 961         bfd_zalloc
 962
 963 SYNOPSIS
 964         void *bfd_zalloc (bfd *abfd, bfd_size_type wanted);
 965
 966 DESCRIPTION
 967         Allocate a block of @var{wanted} bytes of zeroed memory
 968         attached to <<abfd>> and return a pointer to it.
 969 */
 970
 971 void *
 972 bfd_zalloc (bfd *abfd, bfd_size_type size)
 973 {
 974   void *res;
 975
 976   res = bfd_alloc (abfd, size);
 977   if (res)
 978     memset (res, 0, (size_t) size);
 979   return res;
 980 }
 981
 982 /*
 983 INTERNAL_FUNCTION
 984         bfd_zalloc2
 985
 986 SYNOPSIS
 987         void *bfd_zalloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size);
 988
 989 DESCRIPTION
 990         Allocate a block of @var{nmemb} elements of @var{size} bytes each
 991         of zeroed memory attached to <<abfd>> and return a pointer to it.
 992 */
 993
 994 void *
 995 bfd_zalloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size)
 996 {
 997   void *res;
 998
 999   if ((nmemb | size) >= HALF_BFD_SIZE_TYPE
1000       && size != 0
1001       && nmemb > ~(bfd_size_type) 0 / size)
1002     {
1003       bfd_set_error (bfd_error_no_memory);
1004       return NULL;
1005     }
1006
1007   size *= nmemb;
1008
1009   res = bfd_alloc (abfd, size);
1010   if (res)
1011     memset (res, 0, (size_t) size);
1012   return res;
1013 }
1014
1015 /* Free a block allocated for a BFD.
1016    Note:  Also frees all more recently allocated blocks!  */
1017
1018 void
1019 bfd_release (bfd *abfd, void *block)
1020 {
1021   objalloc_free_block ((struct objalloc *) abfd->memory, block);
1022 }
1023
1024
1025 /*
1026    GNU Extension: separate debug-info files
1027
1028    The idea here is that a special section called .gnu_debuglink might be
1029    embedded in a binary file, which indicates that some *other* file
1030    contains the real debugging information. This special section contains a
1031    filename and CRC32 checksum, which we read and resolve to another file,
1032    if it exists.
1033
1034    This facilitates "optional" provision of debugging information, without
1035    having to provide two complete copies of every binary object (with and
1036    without debug symbols).
1037 */
1038
1039 #define GNU_DEBUGLINK   ".gnu_debuglink"
1040 /*
1041 FUNCTION
1042         bfd_calc_gnu_debuglink_crc32
1043
1044 SYNOPSIS
1045         unsigned long bfd_calc_gnu_debuglink_crc32
1046           (unsigned long crc, const unsigned char *buf, bfd_size_type len);
1047
1048 DESCRIPTION
1049         Computes a CRC value as used in the .gnu_debuglink section.
1050         Advances the previously computed @var{crc} value by computing
1051         and adding in the crc32 for @var{len} bytes of @var{buf}.
1052
1053 RETURNS
1054         Return the updated CRC32 value.
1055 */
1056
1057 unsigned long
1058 bfd_calc_gnu_debuglink_crc32 (unsigned long crc,
1059                               const unsigned char *buf,
1060                               bfd_size_type len)
1061 {
1062   static const unsigned long crc32_table[256] =
1063     {
1064       0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419,
1065       0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4,
1066       0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07,
1067       0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de,
1068       0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856,
1069       0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9,
1070       0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4,
1071       0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b,
1072       0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3,
1073       0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a,
1074       0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599,
1075       0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924,
1076       0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190,
1077       0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f,
1078       0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e,
1079       0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01,
1080       0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed,
1081       0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950,
1082       0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3,
1083       0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2,
1084       0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a,
1085       0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5,
1086       0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010,
1087       0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f,
1088       0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17,
1089       0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6,
1090       0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615,
1091       0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8,
1092       0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344,
1093       0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb,
1094       0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a,
1095       0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5,
1096       0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1,
1097       0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c,
1098       0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef,
1099       0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236,
1100       0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe,
1101       0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31,
1102       0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c,
1103       0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713,
1104       0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b,
1105       0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242,
1106       0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1,
1107       0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c,
1108       0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278,
1109       0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7,
1110       0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66,
1111       0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9,
1112       0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605,
1113       0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8,
1114       0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b,
1115       0x2d02ef8d
1116     };
1117   const unsigned char *end;
1118
1119   crc = ~crc & 0xffffffff;
1120   for (end = buf + len; buf < end; ++ buf)
1121     crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8);
1122   return ~crc & 0xffffffff;;
1123 }
1124
1125
1126 /*
1127 INTERNAL_FUNCTION
1128         get_debug_link_info
1129
1130 SYNOPSIS
1131         char *get_debug_link_info (bfd *abfd, unsigned long *crc32_out);
1132
1133 DESCRIPTION
1134         fetch the filename and CRC32 value for any separate debuginfo
1135         associated with @var{abfd}. Return NULL if no such info found,
1136         otherwise return filename and update @var{crc32_out}.
1137 */
1138
1139 static char *
1140 get_debug_link_info (bfd *abfd, unsigned long *crc32_out)
1141 {
1142   asection *sect;
1143   unsigned long crc32;
1144   bfd_byte *contents;
1145   int crc_offset;
1146   char *name;
1147
1148   BFD_ASSERT (abfd);
1149   BFD_ASSERT (crc32_out);
1150
1151   sect = bfd_get_section_by_name (abfd, GNU_DEBUGLINK);
1152
1153   if (sect == NULL)
1154     return NULL;
1155
1156   if (!bfd_malloc_and_get_section (abfd, sect, &contents))
1157     {
1158       if (contents != NULL)
1159         free (contents);
1160       return NULL;
1161     }
1162
1163   /* Crc value is stored after the filename, aligned up to 4 bytes.  */
1164   name = (char *) contents;
1165   crc_offset = strlen (name) + 1;
1166   crc_offset = (crc_offset + 3) & ~3;
1167
1168   crc32 = bfd_get_32 (abfd, contents + crc_offset);
1169
1170   *crc32_out = crc32;
1171   return name;
1172 }
1173
1174 /*
1175 INTERNAL_FUNCTION
1176         separate_debug_file_exists
1177
1178 SYNOPSIS
1179         bfd_boolean separate_debug_file_exists
1180           (char *name, unsigned long crc32);
1181
1182 DESCRIPTION
1183         Checks to see if @var{name} is a file and if its contents
1184         match @var{crc32}.
1185 */
1186
1187 static bfd_boolean
1188 separate_debug_file_exists (const char *name, const unsigned long crc)
1189 {
1190   static unsigned char buffer [8 * 1024];
1191   unsigned long file_crc = 0;
1192   FILE *f;
1193   bfd_size_type count;
1194
1195   BFD_ASSERT (name);
1196
1197   f = real_fopen (name, FOPEN_RB);
1198   if (f == NULL)
1199     return FALSE;
1200
1201   while ((count = fread (buffer, 1, sizeof (buffer), f)) > 0)
1202     file_crc = bfd_calc_gnu_debuglink_crc32 (file_crc, buffer, count);
1203
1204   fclose (f);
1205
1206   return crc == file_crc;
1207 }
1208
1209
1210 /*
1211 INTERNAL_FUNCTION
1212         find_separate_debug_file
1213
1214 SYNOPSIS
1215         char *find_separate_debug_file (bfd *abfd);
1216
1217 DESCRIPTION
1218         Searches @var{abfd} for a reference to separate debugging
1219         information, scans various locations in the filesystem, including
1220         the file tree rooted at @var{debug_file_directory}, and returns a
1221         filename of such debugging information if the file is found and has
1222         matching CRC32.  Returns NULL if no reference to debugging file
1223         exists, or file cannot be found.
1224 */
1225
1226 static char *
1227 find_separate_debug_file (bfd *abfd, const char *debug_file_directory)
1228 {
1229   char *basename;
1230   char *dir;
1231   char *debugfile;
1232   char *canon_dir;
1233   unsigned long crc32;
1234   size_t dirlen;
1235   size_t canon_dirlen;
1236
1237   BFD_ASSERT (abfd);
1238   if (debug_file_directory == NULL)
1239     debug_file_directory = ".";
1240
1241   /* BFD may have been opened from a stream.  */
1242   if (abfd->filename == NULL)
1243     {
1244       bfd_set_error (bfd_error_invalid_operation);
1245       return NULL;
1246     }
1247
1248   basename = get_debug_link_info (abfd, & crc32);
1249   if (basename == NULL)
1250     return NULL;
1251
1252   if (basename[0] == '\0')
1253     {
1254       free (basename);
1255       bfd_set_error (bfd_error_no_debug_section);
1256       return NULL;
1257     }
1258
1259   for (dirlen = strlen (abfd->filename); dirlen > 0; dirlen--)
1260     if (IS_DIR_SEPARATOR (abfd->filename[dirlen - 1]))
1261       break;
1262
1263   dir = bfd_malloc (dirlen + 1);
1264   if (dir == NULL)
1265     {
1266       free (basename);
1267       return NULL;
1268     }
1269   memcpy (dir, abfd->filename, dirlen);
1270   dir[dirlen] = '\0';
1271
1272   /* Compute the canonical name of the bfd object with all symbolic links
1273      resolved, for use in the global debugfile directory.  */
1274   canon_dir = lrealpath (abfd->filename);
1275   for (canon_dirlen = strlen (canon_dir); canon_dirlen > 0; canon_dirlen--)
1276     if (IS_DIR_SEPARATOR (canon_dir[canon_dirlen - 1]))
1277       break;
1278   canon_dir[canon_dirlen] = '\0';
1279
1280   debugfile = bfd_malloc (strlen (debug_file_directory) + 1
1281                           + (canon_dirlen > dirlen ? canon_dirlen : dirlen)
1282                           + strlen (".debug/")
1283                           + strlen (basename)
1284                           + 1);
1285   if (debugfile == NULL)
1286     {
1287       free (basename);
1288       free (dir);
1289       free (canon_dir);
1290       return NULL;
1291     }
1292
1293   /* First try in the same directory as the original file:  */
1294   strcpy (debugfile, dir);
1295   strcat (debugfile, basename);
1296
1297   if (separate_debug_file_exists (debugfile, crc32))
1298     {
1299       free (basename);
1300       free (dir);
1301       free (canon_dir);
1302       return debugfile;
1303     }
1304
1305   /* Then try in a subdirectory called .debug.  */
1306   strcpy (debugfile, dir);
1307   strcat (debugfile, ".debug/");
1308   strcat (debugfile, basename);
1309
1310   if (separate_debug_file_exists (debugfile, crc32))
1311     {
1312       free (basename);
1313       free (dir);
1314       free (canon_dir);
1315       return debugfile;
1316     }
1317
1318   /* Then try in the global debugfile directory.  */
1319   strcpy (debugfile, debug_file_directory);
1320   dirlen = strlen (debug_file_directory) - 1;
1321   if (dirlen > 0
1322       && debug_file_directory[dirlen] != '/'
1323       && canon_dir[0] != '/')
1324     strcat (debugfile, "/");
1325   strcat (debugfile, canon_dir);
1326   strcat (debugfile, basename);
1327
1328   if (separate_debug_file_exists (debugfile, crc32))
1329     {
1330       free (basename);
1331       free (dir);
1332       free (canon_dir);
1333       return debugfile;
1334     }
1335
1336   free (debugfile);
1337   free (basename);
1338   free (dir);
1339   free (canon_dir);
1340   return NULL;
1341 }
1342
1343
1344 /*
1345 FUNCTION
1346         bfd_follow_gnu_debuglink
1347
1348 SYNOPSIS
1349         char *bfd_follow_gnu_debuglink (bfd *abfd, const char *dir);
1350
1351 DESCRIPTION
1352
1353         Takes a BFD and searches it for a .gnu_debuglink section.  If this
1354         section is found, it examines the section for the name and checksum
1355         of a '.debug' file containing auxiliary debugging information.  It
1356         then searches the filesystem for this .debug file in some standard
1357         locations, including the directory tree rooted at @var{dir}, and if
1358         found returns the full filename.
1359
1360         If @var{dir} is NULL, it will search a default path configured into
1361         libbfd at build time.  [XXX this feature is not currently
1362         implemented].
1363
1364 RETURNS
1365         <<NULL>> on any errors or failure to locate the .debug file,
1366         otherwise a pointer to a heap-allocated string containing the
1367         filename.  The caller is responsible for freeing this string.
1368 */
1369
1370 char *
1371 bfd_follow_gnu_debuglink (bfd *abfd, const char *dir)
1372 {
1373   return find_separate_debug_file (abfd, dir);
1374 }
1375
1376 /*
1377 FUNCTION
1378         bfd_create_gnu_debuglink_section
1379
1380 SYNOPSIS
1381         struct bfd_section *bfd_create_gnu_debuglink_section
1382           (bfd *abfd, const char *filename);
1383
1384 DESCRIPTION
1385
1386         Takes a @var{BFD} and adds a .gnu_debuglink section to it.  The section is sized
1387         to be big enough to contain a link to the specified @var{filename}.
1388
1389 RETURNS
1390         A pointer to the new section is returned if all is ok.  Otherwise <<NULL>> is
1391         returned and bfd_error is set.
1392 */
1393
1394 asection *
1395 bfd_create_gnu_debuglink_section (bfd *abfd, const char *filename)
1396 {
1397   asection *sect;
1398   bfd_size_type debuglink_size;
1399   flagword flags;
1400
1401   if (abfd == NULL || filename == NULL)
1402     {
1403       bfd_set_error (bfd_error_invalid_operation);
1404       return NULL;
1405     }
1406
1407   /* Strip off any path components in filename.  */
1408   filename = lbasename (filename);
1409
1410   sect = bfd_get_section_by_name (abfd, GNU_DEBUGLINK);
1411   if (sect)
1412     {
1413       /* Section already exists.  */
1414       bfd_set_error (bfd_error_invalid_operation);
1415       return NULL;
1416     }
1417
1418   flags = SEC_HAS_CONTENTS | SEC_READONLY | SEC_DEBUGGING;
1419   sect = bfd_make_section_with_flags (abfd, GNU_DEBUGLINK, flags);
1420   if (sect == NULL)
1421     return NULL;
1422
1423   debuglink_size = strlen (filename) + 1;
1424   debuglink_size += 3;
1425   debuglink_size &= ~3;
1426   debuglink_size += 4;
1427
1428   if (! bfd_set_section_size (abfd, sect, debuglink_size))
1429     /* XXX Should we delete the section from the bfd ?  */
1430     return NULL;
1431
1432   return sect;
1433 }
1434
1435
1436 /*
1437 FUNCTION
1438         bfd_fill_in_gnu_debuglink_section
1439
1440 SYNOPSIS
1441         bfd_boolean bfd_fill_in_gnu_debuglink_section
1442           (bfd *abfd, struct bfd_section *sect, const char *filename);
1443
1444 DESCRIPTION
1445
1446         Takes a @var{BFD} and containing a .gnu_debuglink section @var{SECT}
1447         and fills in the contents of the section to contain a link to the
1448         specified @var{filename}.  The filename should be relative to the
1449         current directory.
1450
1451 RETURNS
1452         <<TRUE>> is returned if all is ok.  Otherwise <<FALSE>> is returned
1453         and bfd_error is set.
1454 */
1455
1456 bfd_boolean
1457 bfd_fill_in_gnu_debuglink_section (bfd *abfd,
1458                                    struct bfd_section *sect,
1459                                    const char *filename)
1460 {
1461   bfd_size_type debuglink_size;
1462   unsigned long crc32;
1463   char * contents;
1464   bfd_size_type crc_offset;
1465   FILE * handle;
1466   static unsigned char buffer[8 * 1024];
1467   size_t count;
1468   size_t filelen;
1469
1470   if (abfd == NULL || sect == NULL || filename == NULL)
1471     {
1472       bfd_set_error (bfd_error_invalid_operation);
1473       return FALSE;
1474     }
1475
1476   /* Make sure that we can read the file.
1477      XXX - Should we attempt to locate the debug info file using the same
1478      algorithm as gdb ?  At the moment, since we are creating the
1479      .gnu_debuglink section, we insist upon the user providing us with a
1480      correct-for-section-creation-time path, but this need not conform to
1481      the gdb location algorithm.  */
1482   handle = real_fopen (filename, FOPEN_RB);
1483   if (handle == NULL)
1484     {
1485       bfd_set_error (bfd_error_system_call);
1486       return FALSE;
1487     }
1488
1489   crc32 = 0;
1490   while ((count = fread (buffer, 1, sizeof buffer, handle)) > 0)
1491     crc32 = bfd_calc_gnu_debuglink_crc32 (crc32, buffer, count);
1492   fclose (handle);
1493
1494   /* Strip off any path components in filename,
1495      now that we no longer need them.  */
1496   filename = lbasename (filename);
1497
1498   filelen = strlen (filename);
1499   debuglink_size = filelen + 1;
1500   debuglink_size += 3;
1501   debuglink_size &= ~3;
1502   debuglink_size += 4;
1503
1504   contents = bfd_malloc (debuglink_size);
1505   if (contents == NULL)
1506     {
1507       /* XXX Should we delete the section from the bfd ?  */
1508       return FALSE;
1509     }
1510
1511   crc_offset = debuglink_size - 4;
1512   memcpy (contents, filename, filelen);
1513   memset (contents + filelen, 0, crc_offset - filelen);
1514
1515   bfd_put_32 (abfd, crc32, contents + crc_offset);
1516
1517   if (! bfd_set_section_contents (abfd, sect, contents, 0, debuglink_size))
1518     {
1519       /* XXX Should we delete the section from the bfd ?  */
1520       free (contents);
1521       return FALSE;
1522     }
1523
1524   return TRUE;
1525 }