contrib/gdb-7/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, 2009
   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 *) 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 = (FILE *) 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_func) (struct bfd *nbfd,
 380                                                   void *open_closure),
 381                               void *open_closure,
 382                               file_ptr (*pread_func) (struct bfd *nbfd,
 383                                                       void *stream,
 384                                                       void *buf,
 385                                                       file_ptr nbytes,
 386                                                       file_ptr offset),
 387                               int (*close_func) (struct bfd *nbfd,
 388                                                  void *stream),
 389                               int (*stat_func) (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_func}, accessed using
 397         @var{pread_func} and destroyed using @var{close_func}.
 398
 399         Calls <<bfd_find_target>>, so @var{target} is interpreted as by
 400         that function.
 401
 402         Calls @var{open_func} (which can call <<bfd_zalloc>> and
 403         <<bfd_get_filename>>) to obtain the read-only stream backing
 404         the BFD.  @var{open_func} either succeeds returning the
 405         non-<<NULL>> @var{stream}, or fails returning <<NULL>>
 406         (setting <<bfd_error>>).
 407
 408         Calls @var{pread_func} 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_func} 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_func} when the BFD is later closed using
 415         <<bfd_close>>.  @var{close_func} either succeeds returning 0, or
 416         fails returning -1 (setting <<bfd_error>>).
 417
 418         Calls @var{stat_func} to fill in a stat structure for bfd_stat,
 419         bfd_get_size, and bfd_get_mtime calls.  @var{stat_func} 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 = (struct opncls *) 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 = (struct opncls *) 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 = (struct opncls *) 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 = (struct opncls *) 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 = (struct opncls *) 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_p) (struct bfd *, void *),
 527                  void *open_closure,
 528                  file_ptr (*pread_p) (struct bfd *, void *, void *,
 529                                       file_ptr, file_ptr),
 530                  int (*close_p) (struct bfd *, void *),
 531                  int (*stat_p) (struct bfd *, void *, struct stat *))
 532 {
 533   bfd *nbfd;
 534   const bfd_target *target_vec;
 535   struct opncls *vec;
 536   void *stream;
 537
 538   nbfd = _bfd_new_bfd ();
 539   if (nbfd == NULL)
 540     return NULL;
 541
 542   target_vec = bfd_find_target (target, nbfd);
 543   if (target_vec == NULL)
 544     {
 545       _bfd_delete_bfd (nbfd);
 546       return NULL;
 547     }
 548
 549   nbfd->filename = filename;
 550   nbfd->direction = read_direction;
 551
 552   /* `open_p (...)' would get expanded by an the open(2) syscall macro.  */
 553   stream = (*open_p) (nbfd, open_closure);
 554   if (stream == NULL)
 555     {
 556       _bfd_delete_bfd (nbfd);
 557       return NULL;
 558     }
 559
 560   vec = (struct opncls *) bfd_zalloc (nbfd, sizeof (struct opncls));
 561   vec->stream = stream;
 562   vec->pread = pread_p;
 563   vec->close = close_p;
 564   vec->stat = stat_p;
 565
 566   nbfd->iovec = &opncls_iovec;
 567   nbfd->iostream = vec;
 568
 569   return nbfd;
 570 }
 571 \f
 572 /* bfd_openw -- open for writing.
 573    Returns a pointer to a freshly-allocated BFD on success, or NULL.
 574
 575    See comment by bfd_fdopenr before you try to modify this function.  */
 576
 577 /*
 578 FUNCTION
 579         bfd_openw
 580
 581 SYNOPSIS
 582         bfd *bfd_openw (const char *filename, const char *target);
 583
 584 DESCRIPTION
 585         Create a BFD, associated with file @var{filename}, using the
 586         file format @var{target}, and return a pointer to it.
 587
 588         Possible errors are <<bfd_error_system_call>>, <<bfd_error_no_memory>>,
 589         <<bfd_error_invalid_target>>.
 590 */
 591
 592 bfd *
 593 bfd_openw (const char *filename, const char *target)
 594 {
 595   bfd *nbfd;
 596   const bfd_target *target_vec;
 597
 598   /* nbfd has to point to head of malloc'ed block so that bfd_close may
 599      reclaim it correctly.  */
 600   nbfd = _bfd_new_bfd ();
 601   if (nbfd == NULL)
 602     return NULL;
 603
 604   target_vec = bfd_find_target (target, nbfd);
 605   if (target_vec == NULL)
 606     {
 607       _bfd_delete_bfd (nbfd);
 608       return NULL;
 609     }
 610
 611   nbfd->filename = filename;
 612   nbfd->direction = write_direction;
 613
 614   if (bfd_open_file (nbfd) == NULL)
 615     {
 616       /* File not writeable, etc.  */
 617       bfd_set_error (bfd_error_system_call);
 618       _bfd_delete_bfd (nbfd);
 619       return NULL;
 620   }
 621
 622   return nbfd;
 623 }
 624
 625 static inline void
 626 _maybe_make_executable (bfd * abfd)
 627 {
 628   /* If the file was open for writing and is now executable,
 629      make it so.  */
 630   if (abfd->direction == write_direction
 631       && (abfd->flags & (EXEC_P | DYNAMIC)) != 0)
 632     {
 633       struct stat buf;
 634
 635       if (stat (abfd->filename, &buf) == 0
 636           /* Do not attempt to change non-regular files.  This is
 637              here especially for configure scripts and kernel builds
 638              which run tests with "ld [...] -o /dev/null".  */
 639           && S_ISREG(buf.st_mode))
 640         {
 641           unsigned int mask = umask (0);
 642
 643           umask (mask);
 644           chmod (abfd->filename,
 645                  (0777
 646                   & (buf.st_mode | ((S_IXUSR | S_IXGRP | S_IXOTH) &~ mask))));
 647         }
 648     }
 649 }
 650
 651 /*
 652
 653 FUNCTION
 654         bfd_close
 655
 656 SYNOPSIS
 657         bfd_boolean bfd_close (bfd *abfd);
 658
 659 DESCRIPTION
 660
 661         Close a BFD. If the BFD was open for writing, then pending
 662         operations are completed and the file written out and closed.
 663         If the created file is executable, then <<chmod>> is called
 664         to mark it as such.
 665
 666         All memory attached to the BFD is released.
 667
 668         The file descriptor associated with the BFD is closed (even
 669         if it was passed in to BFD by <<bfd_fdopenr>>).
 670
 671 RETURNS
 672         <<TRUE>> is returned if all is ok, otherwise <<FALSE>>.
 673 */
 674
 675
 676 bfd_boolean
 677 bfd_close (bfd *abfd)
 678 {
 679   bfd_boolean ret;
 680   bfd *nbfd;
 681   bfd *next;
 682
 683   if (bfd_write_p (abfd))
 684     {
 685       if (! BFD_SEND_FMT (abfd, _bfd_write_contents, (abfd)))
 686         return FALSE;
 687     }
 688
 689   /* Close nested archives (if this bfd is a thin archive).  */
 690   for (nbfd = abfd->nested_archives; nbfd; nbfd = next)
 691     {
 692       next = nbfd->archive_next;
 693       bfd_close (nbfd);
 694     }
 695
 696   if (! BFD_SEND (abfd, _close_and_cleanup, (abfd)))
 697     return FALSE;
 698
 699   ret = abfd->iovec->bclose (abfd);
 700
 701   if (ret)
 702     _maybe_make_executable (abfd);
 703
 704   _bfd_delete_bfd (abfd);
 705
 706   return ret;
 707 }
 708
 709 /*
 710 FUNCTION
 711         bfd_close_all_done
 712
 713 SYNOPSIS
 714         bfd_boolean bfd_close_all_done (bfd *);
 715
 716 DESCRIPTION
 717         Close a BFD.  Differs from <<bfd_close>> since it does not
 718         complete any pending operations.  This routine would be used
 719         if the application had just used BFD for swapping and didn't
 720         want to use any of the writing code.
 721
 722         If the created file is executable, then <<chmod>> is called
 723         to mark it as such.
 724
 725         All memory attached to the BFD is released.
 726
 727 RETURNS
 728         <<TRUE>> is returned if all is ok, otherwise <<FALSE>>.
 729 */
 730
 731 bfd_boolean
 732 bfd_close_all_done (bfd *abfd)
 733 {
 734   bfd_boolean ret;
 735
 736   ret = bfd_cache_close (abfd);
 737
 738   if (ret)
 739     _maybe_make_executable (abfd);
 740
 741   _bfd_delete_bfd (abfd);
 742
 743   return ret;
 744 }
 745
 746 /*
 747 FUNCTION
 748         bfd_create
 749
 750 SYNOPSIS
 751         bfd *bfd_create (const char *filename, bfd *templ);
 752
 753 DESCRIPTION
 754         Create a new BFD in the manner of <<bfd_openw>>, but without
 755         opening a file. The new BFD takes the target from the target
 756         used by @var{template}. The format is always set to <<bfd_object>>.
 757 */
 758
 759 bfd *
 760 bfd_create (const char *filename, bfd *templ)
 761 {
 762   bfd *nbfd;
 763
 764   nbfd = _bfd_new_bfd ();
 765   if (nbfd == NULL)
 766     return NULL;
 767   nbfd->filename = filename;
 768   if (templ)
 769     nbfd->xvec = templ->xvec;
 770   nbfd->direction = no_direction;
 771   bfd_set_format (nbfd, bfd_object);
 772
 773   return nbfd;
 774 }
 775
 776 /*
 777 FUNCTION
 778         bfd_make_writable
 779
 780 SYNOPSIS
 781         bfd_boolean bfd_make_writable (bfd *abfd);
 782
 783 DESCRIPTION
 784         Takes a BFD as created by <<bfd_create>> and converts it
 785         into one like as returned by <<bfd_openw>>.  It does this
 786         by converting the BFD to BFD_IN_MEMORY.  It's assumed that
 787         you will call <<bfd_make_readable>> on this bfd later.
 788
 789 RETURNS
 790         <<TRUE>> is returned if all is ok, otherwise <<FALSE>>.
 791 */
 792
 793 bfd_boolean
 794 bfd_make_writable (bfd *abfd)
 795 {
 796   struct bfd_in_memory *bim;
 797
 798   if (abfd->direction != no_direction)
 799     {
 800       bfd_set_error (bfd_error_invalid_operation);
 801       return FALSE;
 802     }
 803
 804   bim = (struct bfd_in_memory *) bfd_malloc (sizeof (struct bfd_in_memory));
 805   if (bim == NULL)
 806     return FALSE;       /* bfd_error already set.  */
 807   abfd->iostream = bim;
 808   /* bfd_bwrite will grow these as needed.  */
 809   bim->size = 0;
 810   bim->buffer = 0;
 811
 812   abfd->flags |= BFD_IN_MEMORY;
 813   abfd->iovec = &_bfd_memory_iovec;
 814   abfd->origin = 0;
 815   abfd->direction = write_direction;
 816   abfd->where = 0;
 817
 818   return TRUE;
 819 }
 820
 821 /*
 822 FUNCTION
 823         bfd_make_readable
 824
 825 SYNOPSIS
 826         bfd_boolean bfd_make_readable (bfd *abfd);
 827
 828 DESCRIPTION
 829         Takes a BFD as created by <<bfd_create>> and
 830         <<bfd_make_writable>> and converts it into one like as
 831         returned by <<bfd_openr>>.  It does this by writing the
 832         contents out to the memory buffer, then reversing the
 833         direction.
 834
 835 RETURNS
 836         <<TRUE>> is returned if all is ok, otherwise <<FALSE>>.  */
 837
 838 bfd_boolean
 839 bfd_make_readable (bfd *abfd)
 840 {
 841   if (abfd->direction != write_direction || !(abfd->flags & BFD_IN_MEMORY))
 842     {
 843       bfd_set_error (bfd_error_invalid_operation);
 844       return FALSE;
 845     }
 846
 847   if (! BFD_SEND_FMT (abfd, _bfd_write_contents, (abfd)))
 848     return FALSE;
 849
 850   if (! BFD_SEND (abfd, _close_and_cleanup, (abfd)))
 851     return FALSE;
 852
 853   abfd->arch_info = &bfd_default_arch_struct;
 854
 855   abfd->where = 0;
 856   abfd->format = bfd_unknown;
 857   abfd->my_archive = NULL;
 858   abfd->origin = 0;
 859   abfd->opened_once = FALSE;
 860   abfd->output_has_begun = FALSE;
 861   abfd->section_count = 0;
 862   abfd->usrdata = NULL;
 863   abfd->cacheable = FALSE;
 864   abfd->flags = BFD_IN_MEMORY;
 865   abfd->mtime_set = FALSE;
 866
 867   abfd->target_defaulted = TRUE;
 868   abfd->direction = read_direction;
 869   abfd->sections = 0;
 870   abfd->symcount = 0;
 871   abfd->outsymbols = 0;
 872   abfd->tdata.any = 0;
 873
 874   bfd_section_list_clear (abfd);
 875   bfd_check_format (abfd, bfd_object);
 876
 877   return TRUE;
 878 }
 879
 880 /*
 881 INTERNAL_FUNCTION
 882         bfd_alloc
 883
 884 SYNOPSIS
 885         void *bfd_alloc (bfd *abfd, bfd_size_type wanted);
 886
 887 DESCRIPTION
 888         Allocate a block of @var{wanted} bytes of memory attached to
 889         <<abfd>> and return a pointer to it.
 890 */
 891
 892 void *
 893 bfd_alloc (bfd *abfd, bfd_size_type size)
 894 {
 895   void *ret;
 896
 897   if (size != (unsigned long) size)
 898     {
 899       bfd_set_error (bfd_error_no_memory);
 900       return NULL;
 901     }
 902
 903   ret = objalloc_alloc ((struct objalloc *) abfd->memory, (unsigned long) size);
 904   if (ret == NULL)
 905     bfd_set_error (bfd_error_no_memory);
 906   return ret;
 907 }
 908
 909 /*
 910 INTERNAL_FUNCTION
 911         bfd_alloc2
 912
 913 SYNOPSIS
 914         void *bfd_alloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size);
 915
 916 DESCRIPTION
 917         Allocate a block of @var{nmemb} elements of @var{size} bytes each
 918         of memory attached to <<abfd>> and return a pointer to it.
 919 */
 920
 921 void *
 922 bfd_alloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size)
 923 {
 924   void *ret;
 925
 926   if ((nmemb | size) >= HALF_BFD_SIZE_TYPE
 927       && size != 0
 928       && nmemb > ~(bfd_size_type) 0 / size)
 929     {
 930       bfd_set_error (bfd_error_no_memory);
 931       return NULL;
 932     }
 933
 934   size *= nmemb;
 935
 936   if (size != (unsigned long) size)
 937     {
 938       bfd_set_error (bfd_error_no_memory);
 939       return NULL;
 940     }
 941
 942   ret = objalloc_alloc ((struct objalloc *) abfd->memory, (unsigned long) size);
 943   if (ret == NULL)
 944     bfd_set_error (bfd_error_no_memory);
 945   return ret;
 946 }
 947
 948 /*
 949 INTERNAL_FUNCTION
 950         bfd_zalloc
 951
 952 SYNOPSIS
 953         void *bfd_zalloc (bfd *abfd, bfd_size_type wanted);
 954
 955 DESCRIPTION
 956         Allocate a block of @var{wanted} bytes of zeroed memory
 957         attached to <<abfd>> and return a pointer to it.
 958 */
 959
 960 void *
 961 bfd_zalloc (bfd *abfd, bfd_size_type size)
 962 {
 963   void *res;
 964
 965   res = bfd_alloc (abfd, size);
 966   if (res)
 967     memset (res, 0, (size_t) size);
 968   return res;
 969 }
 970
 971 /*
 972 INTERNAL_FUNCTION
 973         bfd_zalloc2
 974
 975 SYNOPSIS
 976         void *bfd_zalloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size);
 977
 978 DESCRIPTION
 979         Allocate a block of @var{nmemb} elements of @var{size} bytes each
 980         of zeroed memory attached to <<abfd>> and return a pointer to it.
 981 */
 982
 983 void *
 984 bfd_zalloc2 (bfd *abfd, bfd_size_type nmemb, bfd_size_type size)
 985 {
 986   void *res;
 987
 988   if ((nmemb | size) >= HALF_BFD_SIZE_TYPE
 989       && size != 0
 990       && nmemb > ~(bfd_size_type) 0 / size)
 991     {
 992       bfd_set_error (bfd_error_no_memory);
 993       return NULL;
 994     }
 995
 996   size *= nmemb;
 997
 998   res = bfd_alloc (abfd, size);
 999   if (res)
1000     memset (res, 0, (size_t) size);
1001   return res;
1002 }
1003
1004 /* Free a block allocated for a BFD.
1005    Note:  Also frees all more recently allocated blocks!  */
1006
1007 void
1008 bfd_release (bfd *abfd, void *block)
1009 {
1010   objalloc_free_block ((struct objalloc *) abfd->memory, block);
1011 }
1012
1013
1014 /*
1015    GNU Extension: separate debug-info files
1016
1017    The idea here is that a special section called .gnu_debuglink might be
1018    embedded in a binary file, which indicates that some *other* file
1019    contains the real debugging information. This special section contains a
1020    filename and CRC32 checksum, which we read and resolve to another file,
1021    if it exists.
1022
1023    This facilitates "optional" provision of debugging information, without
1024    having to provide two complete copies of every binary object (with and
1025    without debug symbols).
1026 */
1027
1028 #define GNU_DEBUGLINK   ".gnu_debuglink"
1029 /*
1030 FUNCTION
1031         bfd_calc_gnu_debuglink_crc32
1032
1033 SYNOPSIS
1034         unsigned long bfd_calc_gnu_debuglink_crc32
1035           (unsigned long crc, const unsigned char *buf, bfd_size_type len);
1036
1037 DESCRIPTION
1038         Computes a CRC value as used in the .gnu_debuglink section.
1039         Advances the previously computed @var{crc} value by computing
1040         and adding in the crc32 for @var{len} bytes of @var{buf}.
1041
1042 RETURNS
1043         Return the updated CRC32 value.
1044 */
1045
1046 unsigned long
1047 bfd_calc_gnu_debuglink_crc32 (unsigned long crc,
1048                               const unsigned char *buf,
1049                               bfd_size_type len)
1050 {
1051   static const unsigned long crc32_table[256] =
1052     {
1053       0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419,
1054       0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4,
1055       0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07,
1056       0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de,
1057       0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856,
1058       0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9,
1059       0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4,
1060       0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b,
1061       0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3,
1062       0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a,
1063       0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599,
1064       0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924,
1065       0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190,
1066       0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f,
1067       0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e,
1068       0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01,
1069       0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed,
1070       0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950,
1071       0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3,
1072       0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2,
1073       0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a,
1074       0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5,
1075       0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010,
1076       0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f,
1077       0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17,
1078       0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6,
1079       0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615,
1080       0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8,
1081       0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344,
1082       0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb,
1083       0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a,
1084       0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5,
1085       0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1,
1086       0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c,
1087       0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef,
1088       0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236,
1089       0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe,
1090       0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31,
1091       0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c,
1092       0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713,
1093       0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b,
1094       0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242,
1095       0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1,
1096       0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c,
1097       0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278,
1098       0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7,
1099       0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66,
1100       0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9,
1101       0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605,
1102       0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8,
1103       0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b,
1104       0x2d02ef8d
1105     };
1106   const unsigned char *end;
1107
1108   crc = ~crc & 0xffffffff;
1109   for (end = buf + len; buf < end; ++ buf)
1110     crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8);
1111   return ~crc & 0xffffffff;;
1112 }
1113
1114
1115 /*
1116 INTERNAL_FUNCTION
1117         get_debug_link_info
1118
1119 SYNOPSIS
1120         char *get_debug_link_info (bfd *abfd, unsigned long *crc32_out);
1121
1122 DESCRIPTION
1123         fetch the filename and CRC32 value for any separate debuginfo
1124         associated with @var{abfd}. Return NULL if no such info found,
1125         otherwise return filename and update @var{crc32_out}.
1126 */
1127
1128 static char *
1129 get_debug_link_info (bfd *abfd, unsigned long *crc32_out)
1130 {
1131   asection *sect;
1132   unsigned long crc32;
1133   bfd_byte *contents;
1134   int crc_offset;
1135   char *name;
1136
1137   BFD_ASSERT (abfd);
1138   BFD_ASSERT (crc32_out);
1139
1140   sect = bfd_get_section_by_name (abfd, GNU_DEBUGLINK);
1141
1142   if (sect == NULL)
1143     return NULL;
1144
1145   if (!bfd_malloc_and_get_section (abfd, sect, &contents))
1146     {
1147       if (contents != NULL)
1148         free (contents);
1149       return NULL;
1150     }
1151
1152   /* Crc value is stored after the filename, aligned up to 4 bytes.  */
1153   name = (char *) contents;
1154   crc_offset = strlen (name) + 1;
1155   crc_offset = (crc_offset + 3) & ~3;
1156
1157   crc32 = bfd_get_32 (abfd, contents + crc_offset);
1158
1159   *crc32_out = crc32;
1160   return name;
1161 }
1162
1163 /*
1164 INTERNAL_FUNCTION
1165         separate_debug_file_exists
1166
1167 SYNOPSIS
1168         bfd_boolean separate_debug_file_exists
1169           (char *name, unsigned long crc32);
1170
1171 DESCRIPTION
1172         Checks to see if @var{name} is a file and if its contents
1173         match @var{crc32}.
1174 */
1175
1176 static bfd_boolean
1177 separate_debug_file_exists (const char *name, const unsigned long crc)
1178 {
1179   static unsigned char buffer [8 * 1024];
1180   unsigned long file_crc = 0;
1181   FILE *f;
1182   bfd_size_type count;
1183
1184   BFD_ASSERT (name);
1185
1186   f = real_fopen (name, FOPEN_RB);
1187   if (f == NULL)
1188     return FALSE;
1189
1190   while ((count = fread (buffer, 1, sizeof (buffer), f)) > 0)
1191     file_crc = bfd_calc_gnu_debuglink_crc32 (file_crc, buffer, count);
1192
1193   fclose (f);
1194
1195   return crc == file_crc;
1196 }
1197
1198
1199 /*
1200 INTERNAL_FUNCTION
1201         find_separate_debug_file
1202
1203 SYNOPSIS
1204         char *find_separate_debug_file (bfd *abfd);
1205
1206 DESCRIPTION
1207         Searches @var{abfd} for a reference to separate debugging
1208         information, scans various locations in the filesystem, including
1209         the file tree rooted at @var{debug_file_directory}, and returns a
1210         filename of such debugging information if the file is found and has
1211         matching CRC32.  Returns NULL if no reference to debugging file
1212         exists, or file cannot be found.
1213 */
1214
1215 static char *
1216 find_separate_debug_file (bfd *abfd, const char *debug_file_directory)
1217 {
1218   char *base;
1219   char *dir;
1220   char *debugfile;
1221   char *canon_dir;
1222   unsigned long crc32;
1223   size_t dirlen;
1224   size_t canon_dirlen;
1225
1226   BFD_ASSERT (abfd);
1227   if (debug_file_directory == NULL)
1228     debug_file_directory = ".";
1229
1230   /* BFD may have been opened from a stream.  */
1231   if (abfd->filename == NULL)
1232     {
1233       bfd_set_error (bfd_error_invalid_operation);
1234       return NULL;
1235     }
1236
1237   base = get_debug_link_info (abfd, & crc32);
1238   if (base == NULL)
1239     return NULL;
1240
1241   if (base[0] == '\0')
1242     {
1243       free (base);
1244       bfd_set_error (bfd_error_no_debug_section);
1245       return NULL;
1246     }
1247
1248   for (dirlen = strlen (abfd->filename); dirlen > 0; dirlen--)
1249     if (IS_DIR_SEPARATOR (abfd->filename[dirlen - 1]))
1250       break;
1251
1252   dir = (char *) bfd_malloc (dirlen + 1);
1253   if (dir == NULL)
1254     {
1255       free (base);
1256       return NULL;
1257     }
1258   memcpy (dir, abfd->filename, dirlen);
1259   dir[dirlen] = '\0';
1260
1261   /* Compute the canonical name of the bfd object with all symbolic links
1262      resolved, for use in the global debugfile directory.  */
1263   canon_dir = lrealpath (abfd->filename);
1264   for (canon_dirlen = strlen (canon_dir); canon_dirlen > 0; canon_dirlen--)
1265     if (IS_DIR_SEPARATOR (canon_dir[canon_dirlen - 1]))
1266       break;
1267   canon_dir[canon_dirlen] = '\0';
1268
1269   debugfile = (char *)
1270       bfd_malloc (strlen (debug_file_directory) + 1
1271                   + (canon_dirlen > dirlen ? canon_dirlen : dirlen)
1272                   + strlen (".debug/")
1273                   + strlen (base)
1274                   + 1);
1275   if (debugfile == NULL)
1276     {
1277       free (base);
1278       free (dir);
1279       free (canon_dir);
1280       return NULL;
1281     }
1282
1283   /* First try in the same directory as the original file:  */
1284   strcpy (debugfile, dir);
1285   strcat (debugfile, base);
1286
1287   if (separate_debug_file_exists (debugfile, crc32))
1288     {
1289       free (base);
1290       free (dir);
1291       free (canon_dir);
1292       return debugfile;
1293     }
1294
1295   /* Then try in a subdirectory called .debug.  */
1296   strcpy (debugfile, dir);
1297   strcat (debugfile, ".debug/");
1298   strcat (debugfile, base);
1299
1300   if (separate_debug_file_exists (debugfile, crc32))
1301     {
1302       free (base);
1303       free (dir);
1304       free (canon_dir);
1305       return debugfile;
1306     }
1307
1308   /* Then try in the global debugfile directory.  */
1309   strcpy (debugfile, debug_file_directory);
1310   dirlen = strlen (debug_file_directory) - 1;
1311   if (dirlen > 0
1312       && debug_file_directory[dirlen] != '/'
1313       && canon_dir[0] != '/')
1314     strcat (debugfile, "/");
1315   strcat (debugfile, canon_dir);
1316   strcat (debugfile, base);
1317
1318   if (separate_debug_file_exists (debugfile, crc32))
1319     {
1320       free (base);
1321       free (dir);
1322       free (canon_dir);
1323       return debugfile;
1324     }
1325
1326   free (debugfile);
1327   free (base);
1328   free (dir);
1329   free (canon_dir);
1330   return NULL;
1331 }
1332
1333
1334 /*
1335 FUNCTION
1336         bfd_follow_gnu_debuglink
1337
1338 SYNOPSIS
1339         char *bfd_follow_gnu_debuglink (bfd *abfd, const char *dir);
1340
1341 DESCRIPTION
1342
1343         Takes a BFD and searches it for a .gnu_debuglink section.  If this
1344         section is found, it examines the section for the name and checksum
1345         of a '.debug' file containing auxiliary debugging information.  It
1346         then searches the filesystem for this .debug file in some standard
1347         locations, including the directory tree rooted at @var{dir}, and if
1348         found returns the full filename.
1349
1350         If @var{dir} is NULL, it will search a default path configured into
1351         libbfd at build time.  [XXX this feature is not currently
1352         implemented].
1353
1354 RETURNS
1355         <<NULL>> on any errors or failure to locate the .debug file,
1356         otherwise a pointer to a heap-allocated string containing the
1357         filename.  The caller is responsible for freeing this string.
1358 */
1359
1360 char *
1361 bfd_follow_gnu_debuglink (bfd *abfd, const char *dir)
1362 {
1363   return find_separate_debug_file (abfd, dir);
1364 }
1365
1366 /*
1367 FUNCTION
1368         bfd_create_gnu_debuglink_section
1369
1370 SYNOPSIS
1371         struct bfd_section *bfd_create_gnu_debuglink_section
1372           (bfd *abfd, const char *filename);
1373
1374 DESCRIPTION
1375
1376         Takes a @var{BFD} and adds a .gnu_debuglink section to it.  The section is sized
1377         to be big enough to contain a link to the specified @var{filename}.
1378
1379 RETURNS
1380         A pointer to the new section is returned if all is ok.  Otherwise <<NULL>> is
1381         returned and bfd_error is set.
1382 */
1383
1384 asection *
1385 bfd_create_gnu_debuglink_section (bfd *abfd, const char *filename)
1386 {
1387   asection *sect;
1388   bfd_size_type debuglink_size;
1389   flagword flags;
1390
1391   if (abfd == NULL || filename == NULL)
1392     {
1393       bfd_set_error (bfd_error_invalid_operation);
1394       return NULL;
1395     }
1396
1397   /* Strip off any path components in filename.  */
1398   filename = lbasename (filename);
1399
1400   sect = bfd_get_section_by_name (abfd, GNU_DEBUGLINK);
1401   if (sect)
1402     {
1403       /* Section already exists.  */
1404       bfd_set_error (bfd_error_invalid_operation);
1405       return NULL;
1406     }
1407
1408   flags = SEC_HAS_CONTENTS | SEC_READONLY | SEC_DEBUGGING;
1409   sect = bfd_make_section_with_flags (abfd, GNU_DEBUGLINK, flags);
1410   if (sect == NULL)
1411     return NULL;
1412
1413   debuglink_size = strlen (filename) + 1;
1414   debuglink_size += 3;
1415   debuglink_size &= ~3;
1416   debuglink_size += 4;
1417
1418   if (! bfd_set_section_size (abfd, sect, debuglink_size))
1419     /* XXX Should we delete the section from the bfd ?  */
1420     return NULL;
1421
1422   return sect;
1423 }
1424
1425
1426 /*
1427 FUNCTION
1428         bfd_fill_in_gnu_debuglink_section
1429
1430 SYNOPSIS
1431         bfd_boolean bfd_fill_in_gnu_debuglink_section
1432           (bfd *abfd, struct bfd_section *sect, const char *filename);
1433
1434 DESCRIPTION
1435
1436         Takes a @var{BFD} and containing a .gnu_debuglink section @var{SECT}
1437         and fills in the contents of the section to contain a link to the
1438         specified @var{filename}.  The filename should be relative to the
1439         current directory.
1440
1441 RETURNS
1442         <<TRUE>> is returned if all is ok.  Otherwise <<FALSE>> is returned
1443         and bfd_error is set.
1444 */
1445
1446 bfd_boolean
1447 bfd_fill_in_gnu_debuglink_section (bfd *abfd,
1448                                    struct bfd_section *sect,
1449                                    const char *filename)
1450 {
1451   bfd_size_type debuglink_size;
1452   unsigned long crc32;
1453   char * contents;
1454   bfd_size_type crc_offset;
1455   FILE * handle;
1456   static unsigned char buffer[8 * 1024];
1457   size_t count;
1458   size_t filelen;
1459
1460   if (abfd == NULL || sect == NULL || filename == NULL)
1461     {
1462       bfd_set_error (bfd_error_invalid_operation);
1463       return FALSE;
1464     }
1465
1466   /* Make sure that we can read the file.
1467      XXX - Should we attempt to locate the debug info file using the same
1468      algorithm as gdb ?  At the moment, since we are creating the
1469      .gnu_debuglink section, we insist upon the user providing us with a
1470      correct-for-section-creation-time path, but this need not conform to
1471      the gdb location algorithm.  */
1472   handle = real_fopen (filename, FOPEN_RB);
1473   if (handle == NULL)
1474     {
1475       bfd_set_error (bfd_error_system_call);
1476       return FALSE;
1477     }
1478
1479   crc32 = 0;
1480   while ((count = fread (buffer, 1, sizeof buffer, handle)) > 0)
1481     crc32 = bfd_calc_gnu_debuglink_crc32 (crc32, buffer, count);
1482   fclose (handle);
1483
1484   /* Strip off any path components in filename,
1485      now that we no longer need them.  */
1486   filename = lbasename (filename);
1487
1488   filelen = strlen (filename);
1489   debuglink_size = filelen + 1;
1490   debuglink_size += 3;
1491   debuglink_size &= ~3;
1492   debuglink_size += 4;
1493
1494   contents = (char *) bfd_malloc (debuglink_size);
1495   if (contents == NULL)
1496     {
1497       /* XXX Should we delete the section from the bfd ?  */
1498       return FALSE;
1499     }
1500
1501   crc_offset = debuglink_size - 4;
1502   memcpy (contents, filename, filelen);
1503   memset (contents + filelen, 0, crc_offset - filelen);
1504
1505   bfd_put_32 (abfd, crc32, contents + crc_offset);
1506
1507   if (! bfd_set_section_contents (abfd, sect, contents, 0, debuglink_size))
1508     {
1509       /* XXX Should we delete the section from the bfd ?  */
1510       free (contents);
1511       return FALSE;
1512     }
1513
1514   return TRUE;
1515 }