bfd/cache.c

   1 /* BFD library -- caching of file descriptors.
   2
   3    Copyright (C) 1990-2024 Free Software Foundation, Inc.
   4
   5    Hacked by Steve Chamberlain of Cygnus Support (steve@cygnus.com).
   6
   7    This file is part of BFD, the Binary File Descriptor library.
   8
   9    This program is free software; you can redistribute it and/or modify
  10    it under the terms of the GNU General Public License as published by
  11    the Free Software Foundation; either version 3 of the License, or
  12    (at your option) any later version.
  13
  14    This program is distributed in the hope that it will be useful,
  15    but WITHOUT ANY WARRANTY; without even the implied warranty of
  16    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17    GNU General Public License for more details.
  18
  19    You should have received a copy of the GNU General Public License
  20    along with this program; if not, write to the Free Software
  21    Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston,
  22    MA 02110-1301, USA.  */
  23
  24 /*
  25 SECTION
  26         File caching
  27
  28         The file caching mechanism is embedded within BFD and allows
  29         the application to open as many BFDs as it wants without
  30         regard to the underlying operating system's file descriptor
  31         limit (often as low as 20 open files).  The module in
  32         <<cache.c>> maintains a least recently used list of
  33         <<bfd_cache_max_open>> files, and exports the name
  34         <<bfd_cache_lookup>>, which runs around and makes sure that
  35         the required BFD is open. If not, then it chooses a file to
  36         close, closes it and opens the one wanted, returning its file
  37         handle.
  38
  39 SUBSECTION
  40         Caching functions
  41 */
  42
  43 #include "sysdep.h"
  44 #include "bfd.h"
  45 #include "libbfd.h"
  46 #include "libiberty.h"
  47
  48 static FILE *_bfd_open_file_unlocked (bfd *abfd);
  49
  50 /* In some cases we can optimize cache operation when reopening files.
  51    For instance, a flush is entirely unnecessary if the file is already
  52    closed, so a flush would use CACHE_NO_OPEN.  Similarly, a seek using
  53    SEEK_SET or SEEK_END need not first seek to the current position.
  54    For stat we ignore seek errors, just in case the file has changed
  55    while we weren't looking.  If it has, then it's possible that the
  56    file is shorter and we don't want a seek error to prevent us doing
  57    the stat.  */
  58 enum cache_flag {
  59   CACHE_NORMAL = 0,
  60   CACHE_NO_OPEN = 1,
  61   CACHE_NO_SEEK = 2,
  62   CACHE_NO_SEEK_ERROR = 4
  63 };
  64
  65 /* The maximum number of files which the cache will keep open at
  66    one time.  When needed call bfd_cache_max_open to initialize.  */
  67
  68 static unsigned max_open_files = 0;
  69
  70 /* Set max_open_files, if not already set, to 12.5% of the allowed open
  71    file descriptors, but at least 10, and return the value.  */
  72 static unsigned
  73 bfd_cache_max_open (void)
  74 {
  75   if (max_open_files == 0)
  76     {
  77       int max;
  78 #if defined(__sun) && !defined(__sparcv9) && !defined(__x86_64__)
  79       /* PR ld/19260: 32-bit Solaris has very inelegant handling of the 255
  80          file descriptor limit.  The problem is that setrlimit(2) can raise
  81          RLIMIT_NOFILE to a value that is not supported by libc, resulting
  82          in "Too many open files" errors.  This can happen here even though
  83          max_open_files is set to rlim.rlim_cur / 8.  For example, if
  84          a parent process has set rlim.rlim_cur to 65536, then max_open_files
  85          will be computed as 8192.
  86
  87          This check essentially reverts to the behavior from binutils 2.23.1
  88          for 32-bit Solaris only.  (It is hoped that the 32-bit libc
  89          limitation will be removed soon).  64-bit Solaris libc does not have
  90          this limitation.  */
  91       max = 16;
  92 #else
  93 #ifdef HAVE_GETRLIMIT
  94       struct rlimit rlim;
  95
  96       if (getrlimit (RLIMIT_NOFILE, &rlim) == 0
  97           && rlim.rlim_cur != (rlim_t) RLIM_INFINITY)
  98         max = rlim.rlim_cur / 8;
  99       else
 100 #endif
 101 #ifdef _SC_OPEN_MAX
 102         max = sysconf (_SC_OPEN_MAX) / 8;
 103 #else
 104         max = 10;
 105 #endif
 106 #endif /* not 32-bit Solaris */
 107
 108       max_open_files = max < 10 ? 10 : max;
 109     }
 110
 111   return max_open_files;
 112 }
 113
 114 /* The number of BFD files we have open.  */
 115
 116 static unsigned open_files;
 117
 118 /* Zero, or a pointer to the topmost BFD on the chain.  This is
 119    used by the <<bfd_cache_lookup>> macro in @file{libbfd.h} to
 120    determine when it can avoid a function call.  */
 121
 122 static bfd *bfd_last_cache = NULL;
 123
 124 /* Insert a BFD into the cache.  */
 125
 126 static void
 127 insert (bfd *abfd)
 128 {
 129   if (bfd_last_cache == NULL)
 130     {
 131       abfd->lru_next = abfd;
 132       abfd->lru_prev = abfd;
 133     }
 134   else
 135     {
 136       abfd->lru_next = bfd_last_cache;
 137       abfd->lru_prev = bfd_last_cache->lru_prev;
 138       abfd->lru_prev->lru_next = abfd;
 139       abfd->lru_next->lru_prev = abfd;
 140     }
 141   bfd_last_cache = abfd;
 142 }
 143
 144 /* Remove a BFD from the cache.  */
 145
 146 static void
 147 snip (bfd *abfd)
 148 {
 149   abfd->lru_prev->lru_next = abfd->lru_next;
 150   abfd->lru_next->lru_prev = abfd->lru_prev;
 151   if (abfd == bfd_last_cache)
 152     {
 153       bfd_last_cache = abfd->lru_next;
 154       if (abfd == bfd_last_cache)
 155         bfd_last_cache = NULL;
 156     }
 157 }
 158
 159 /* Close a BFD and remove it from the cache.  */
 160
 161 static bool
 162 bfd_cache_delete (bfd *abfd)
 163 {
 164   bool ret;
 165
 166   if (fclose ((FILE *) abfd->iostream) == 0)
 167     ret = true;
 168   else
 169     {
 170       ret = false;
 171       bfd_set_error (bfd_error_system_call);
 172     }
 173
 174   snip (abfd);
 175
 176   abfd->iostream = NULL;
 177   BFD_ASSERT (open_files > 0);
 178   --open_files;
 179   abfd->flags |= BFD_CLOSED_BY_CACHE;
 180
 181   return ret;
 182 }
 183
 184 /* We need to open a new file, and the cache is full.  Find the least
 185    recently used cacheable BFD and close it.  */
 186
 187 static bool
 188 close_one (void)
 189 {
 190   register bfd *to_kill;
 191
 192   if (bfd_last_cache == NULL)
 193     to_kill = NULL;
 194   else
 195     {
 196       for (to_kill = bfd_last_cache->lru_prev;
 197            ! to_kill->cacheable;
 198            to_kill = to_kill->lru_prev)
 199         {
 200           if (to_kill == bfd_last_cache)
 201             {
 202               to_kill = NULL;
 203               break;
 204             }
 205         }
 206     }
 207
 208   if (to_kill == NULL)
 209     {
 210       /* There are no open cacheable BFD's.  */
 211       return true;
 212     }
 213
 214   to_kill->where = _bfd_real_ftell ((FILE *) to_kill->iostream);
 215
 216   return bfd_cache_delete (to_kill);
 217 }
 218
 219 /* Check to see if the required BFD is the same as the last one
 220    looked up. If so, then it can use the stream in the BFD with
 221    impunity, since it can't have changed since the last lookup;
 222    otherwise, it has to perform the complicated lookup function.  */
 223
 224 #define bfd_cache_lookup(x, flag) \
 225   ((x) == bfd_last_cache                        \
 226    ? (FILE *) (bfd_last_cache->iostream)        \
 227    : bfd_cache_lookup_worker (x, flag))
 228
 229 /* Called when the macro <<bfd_cache_lookup>> fails to find a
 230    quick answer.  Find a file descriptor for @var{abfd}.  If
 231    necessary, it open it.  If there are already more than
 232    <<bfd_cache_max_open>> files open, it tries to close one first, to
 233    avoid running out of file descriptors.  It will return NULL
 234    if it is unable to (re)open the @var{abfd}.  */
 235
 236 static FILE *
 237 bfd_cache_lookup_worker (bfd *abfd, enum cache_flag flag)
 238 {
 239   if ((abfd->flags & BFD_IN_MEMORY) != 0)
 240     abort ();
 241
 242   if (abfd->my_archive != NULL
 243       && !bfd_is_thin_archive (abfd->my_archive))
 244     abort ();
 245
 246   if (abfd->iostream != NULL)
 247     {
 248       /* Move the file to the start of the cache.  */
 249       if (abfd != bfd_last_cache)
 250         {
 251           snip (abfd);
 252           insert (abfd);
 253         }
 254       return (FILE *) abfd->iostream;
 255     }
 256
 257   if (flag & CACHE_NO_OPEN)
 258     return NULL;
 259
 260   if (_bfd_open_file_unlocked (abfd) == NULL)
 261     ;
 262   else if (!(flag & CACHE_NO_SEEK)
 263            && _bfd_real_fseek ((FILE *) abfd->iostream,
 264                                abfd->where, SEEK_SET) != 0
 265            && !(flag & CACHE_NO_SEEK_ERROR))
 266     bfd_set_error (bfd_error_system_call);
 267   else
 268     return (FILE *) abfd->iostream;
 269
 270   /* xgettext:c-format */
 271   _bfd_error_handler (_("reopening %pB: %s"),
 272                       abfd, bfd_errmsg (bfd_get_error ()));
 273   return NULL;
 274 }
 275
 276 static file_ptr
 277 cache_btell (struct bfd *abfd)
 278 {
 279   if (!bfd_lock ())
 280     return -1;
 281   FILE *f = bfd_cache_lookup (abfd, CACHE_NO_OPEN);
 282   if (f == NULL)
 283     {
 284       if (!bfd_unlock ())
 285         return -1;
 286       return abfd->where;
 287     }
 288   file_ptr result = _bfd_real_ftell (f);
 289   if (!bfd_unlock ())
 290     return -1;
 291   return result;
 292 }
 293
 294 static int
 295 cache_bseek (struct bfd *abfd, file_ptr offset, int whence)
 296 {
 297   if (!bfd_lock ())
 298     return -1;
 299   FILE *f = bfd_cache_lookup (abfd, whence != SEEK_CUR ? CACHE_NO_SEEK : CACHE_NORMAL);
 300   if (f == NULL)
 301     {
 302       bfd_unlock ();
 303       return -1;
 304     }
 305   int result = _bfd_real_fseek (f, offset, whence);
 306   if (!bfd_unlock ())
 307     return -1;
 308   return result;
 309 }
 310
 311 /* Note that archive entries don't have streams; they share their parent's.
 312    This allows someone to play with the iostream behind BFD's back.
 313
 314    Also, note that the origin pointer points to the beginning of a file's
 315    contents (0 for non-archive elements).  For archive entries this is the
 316    first octet in the file, NOT the beginning of the archive header.  */
 317
 318 static file_ptr
 319 cache_bread_1 (FILE *f, void *buf, file_ptr nbytes)
 320 {
 321   file_ptr nread;
 322
 323 #if defined (__VAX) && defined (VMS)
 324   /* Apparently fread on Vax VMS does not keep the record length
 325      information.  */
 326   nread = read (fileno (f), buf, nbytes);
 327   /* Set bfd_error if we did not read as much data as we expected.  If
 328      the read failed due to an error set the bfd_error_system_call,
 329      else set bfd_error_file_truncated.  */
 330   if (nread == (file_ptr)-1)
 331     {
 332       bfd_set_error (bfd_error_system_call);
 333       return nread;
 334     }
 335 #else
 336   nread = fread (buf, 1, nbytes, f);
 337   /* Set bfd_error if we did not read as much data as we expected.  If
 338      the read failed due to an error set the bfd_error_system_call,
 339      else set bfd_error_file_truncated.  */
 340   if (nread < nbytes && ferror (f))
 341     {
 342       bfd_set_error (bfd_error_system_call);
 343       return nread;
 344     }
 345 #endif
 346   if (nread < nbytes)
 347     /* This may or may not be an error, but in case the calling code
 348        bails out because of it, set the right error code.  */
 349     bfd_set_error (bfd_error_file_truncated);
 350   return nread;
 351 }
 352
 353 static file_ptr
 354 cache_bread (struct bfd *abfd, void *buf, file_ptr nbytes)
 355 {
 356   if (!bfd_lock ())
 357     return -1;
 358   file_ptr nread = 0;
 359   FILE *f;
 360
 361   f = bfd_cache_lookup (abfd, CACHE_NORMAL);
 362   if (f == NULL)
 363     {
 364       bfd_unlock ();
 365       return -1;
 366     }
 367
 368   /* Some filesystems are unable to handle reads that are too large
 369      (for instance, NetApp shares with oplocks turned off).  To avoid
 370      hitting this limitation, we read the buffer in chunks of 8MB max.  */
 371   while (nread < nbytes)
 372     {
 373       const file_ptr max_chunk_size = 0x800000;
 374       file_ptr chunk_size = nbytes - nread;
 375       file_ptr chunk_nread;
 376
 377       if (chunk_size > max_chunk_size)
 378         chunk_size = max_chunk_size;
 379
 380       chunk_nread = cache_bread_1 (f, (char *) buf + nread, chunk_size);
 381
 382       /* Update the nread count.
 383
 384          We just have to be careful of the case when cache_bread_1 returns
 385          a negative count:  If this is our first read, then set nread to
 386          that negative count in order to return that negative value to the
 387          caller.  Otherwise, don't add it to our total count, or we would
 388          end up returning a smaller number of bytes read than we actually
 389          did.  */
 390       if (nread == 0 || chunk_nread > 0)
 391         nread += chunk_nread;
 392
 393       if (chunk_nread < chunk_size)
 394         break;
 395     }
 396
 397   if (!bfd_unlock ())
 398     return -1;
 399   return nread;
 400 }
 401
 402 static file_ptr
 403 cache_bwrite (struct bfd *abfd, const void *from, file_ptr nbytes)
 404 {
 405   if (!bfd_lock ())
 406     return -1;
 407   file_ptr nwrite;
 408   FILE *f = bfd_cache_lookup (abfd, CACHE_NORMAL);
 409
 410   if (f == NULL)
 411     {
 412       if (!bfd_unlock ())
 413         return -1;
 414       return 0;
 415     }
 416   nwrite = fwrite (from, 1, nbytes, f);
 417   if (nwrite < nbytes && ferror (f))
 418     {
 419       bfd_set_error (bfd_error_system_call);
 420       bfd_unlock ();
 421       return -1;
 422     }
 423   if (!bfd_unlock ())
 424     return -1;
 425   return nwrite;
 426 }
 427
 428 static int
 429 cache_bclose (struct bfd *abfd)
 430 {
 431   /* No locking needed here, it's handled by the callee.  */
 432   return bfd_cache_close (abfd) - 1;
 433 }
 434
 435 static int
 436 cache_bflush (struct bfd *abfd)
 437 {
 438   if (!bfd_lock ())
 439     return -1;
 440   int sts;
 441   FILE *f = bfd_cache_lookup (abfd, CACHE_NO_OPEN);
 442
 443   if (f == NULL)
 444     {
 445       if (!bfd_unlock ())
 446         return -1;
 447       return 0;
 448     }
 449   sts = fflush (f);
 450   if (sts < 0)
 451     bfd_set_error (bfd_error_system_call);
 452   if (!bfd_unlock ())
 453     return -1;
 454   return sts;
 455 }
 456
 457 static int
 458 cache_bstat (struct bfd *abfd, struct stat *sb)
 459 {
 460   if (!bfd_lock ())
 461     return -1;
 462   int sts;
 463   FILE *f = bfd_cache_lookup (abfd, CACHE_NO_SEEK_ERROR);
 464
 465   if (f == NULL)
 466     {
 467       bfd_unlock ();
 468       return -1;
 469     }
 470   sts = fstat (fileno (f), sb);
 471   if (sts < 0)
 472     bfd_set_error (bfd_error_system_call);
 473   if (!bfd_unlock ())
 474     return -1;
 475   return sts;
 476 }
 477
 478 static void *
 479 cache_bmmap (struct bfd *abfd ATTRIBUTE_UNUSED,
 480              void *addr ATTRIBUTE_UNUSED,
 481              size_t len ATTRIBUTE_UNUSED,
 482              int prot ATTRIBUTE_UNUSED,
 483              int flags ATTRIBUTE_UNUSED,
 484              file_ptr offset ATTRIBUTE_UNUSED,
 485              void **map_addr ATTRIBUTE_UNUSED,
 486              size_t *map_len ATTRIBUTE_UNUSED)
 487 {
 488   void *ret = MAP_FAILED;
 489
 490   if (!bfd_lock ())
 491     return ret;
 492   if ((abfd->flags & BFD_IN_MEMORY) != 0)
 493     abort ();
 494 #ifdef HAVE_MMAP
 495   else
 496     {
 497       uintptr_t pagesize_m1 = _bfd_pagesize_m1;
 498       FILE *f;
 499       file_ptr pg_offset;
 500       size_t pg_len;
 501
 502       f = bfd_cache_lookup (abfd, CACHE_NO_SEEK_ERROR);
 503       if (f == NULL)
 504         {
 505           bfd_unlock ();
 506           return ret;
 507         }
 508
 509       /* Align.  */
 510       pg_offset = offset & ~pagesize_m1;
 511       pg_len = (len + (offset - pg_offset) + pagesize_m1) & ~pagesize_m1;
 512
 513       ret = mmap (addr, pg_len, prot, flags, fileno (f), pg_offset);
 514       if (ret == MAP_FAILED)
 515         bfd_set_error (bfd_error_system_call);
 516       else
 517         {
 518           *map_addr = ret;
 519           *map_len = pg_len;
 520           ret = (char *) ret + (offset & pagesize_m1);
 521         }
 522     }
 523 #endif
 524
 525   if (!bfd_unlock ())
 526     return MAP_FAILED;
 527   return ret;
 528 }
 529
 530 static const struct bfd_iovec cache_iovec =
 531 {
 532   &cache_bread, &cache_bwrite, &cache_btell, &cache_bseek,
 533   &cache_bclose, &cache_bflush, &cache_bstat, &cache_bmmap
 534 };
 535
 536 static bool
 537 _bfd_cache_init_unlocked (bfd *abfd)
 538 {
 539   BFD_ASSERT (abfd->iostream != NULL);
 540   if (open_files >= bfd_cache_max_open ())
 541     {
 542       if (! close_one ())
 543         return false;
 544     }
 545   abfd->iovec = &cache_iovec;
 546   insert (abfd);
 547   abfd->flags &= ~BFD_CLOSED_BY_CACHE;
 548   ++open_files;
 549   return true;
 550 }
 551
 552 /*
 553 INTERNAL_FUNCTION
 554         bfd_cache_init
 555
 556 SYNOPSIS
 557         bool bfd_cache_init (bfd *abfd);
 558
 559 DESCRIPTION
 560         Add a newly opened BFD to the cache.
 561 */
 562
 563 bool
 564 bfd_cache_init (bfd *abfd)
 565 {
 566   if (!bfd_lock ())
 567     return false;
 568   bool result = _bfd_cache_init_unlocked (abfd);
 569   if (!bfd_unlock ())
 570     return false;
 571   return result;
 572 }
 573
 574 static bool
 575 _bfd_cache_close_unlocked (bfd *abfd)
 576 {
 577   /* Don't remove this test.  bfd_reinit depends on it.  */
 578   if (abfd->iovec != &cache_iovec)
 579     return true;
 580
 581   if (abfd->iostream == NULL)
 582     /* Previously closed.  */
 583     return true;
 584
 585   /* Note: no locking needed in this function, as it is handled by
 586      bfd_cache_delete.  */
 587   return bfd_cache_delete (abfd);
 588 }
 589
 590 /*
 591 FUNCTION
 592         bfd_cache_close
 593
 594 SYNOPSIS
 595         bool bfd_cache_close (bfd *abfd);
 596
 597 DESCRIPTION
 598         Remove the BFD @var{abfd} from the cache. If the attached file is open,
 599         then close it too.
 600
 601         <<FALSE>> is returned if closing the file fails, <<TRUE>> is
 602         returned if all is well.
 603 */
 604
 605 bool
 606 bfd_cache_close (bfd *abfd)
 607 {
 608   if (!bfd_lock ())
 609     return false;
 610   bool result = _bfd_cache_close_unlocked (abfd);
 611   if (!bfd_unlock ())
 612     return false;
 613   return result;
 614 }
 615
 616 /*
 617 FUNCTION
 618         bfd_cache_close_all
 619
 620 SYNOPSIS
 621         bool bfd_cache_close_all (void);
 622
 623 DESCRIPTION
 624         Remove all BFDs from the cache. If the attached file is open,
 625         then close it too.  Note - despite its name this function will
 626         close a BFD even if it is not marked as being cacheable, ie
 627         even if bfd_get_cacheable() returns false.
 628
 629         <<FALSE>> is returned if closing one of the file fails, <<TRUE>> is
 630         returned if all is well.
 631 */
 632
 633 bool
 634 bfd_cache_close_all (void)
 635 {
 636   bool ret = true;
 637
 638   if (!bfd_lock ())
 639     return false;
 640   while (bfd_last_cache != NULL)
 641     {
 642       bfd *prev_bfd_last_cache = bfd_last_cache;
 643
 644       ret &= _bfd_cache_close_unlocked (bfd_last_cache);
 645
 646       /* Stop a potential infinite loop should bfd_cache_close()
 647          not update bfd_last_cache.  */
 648       if (bfd_last_cache == prev_bfd_last_cache)
 649         break;
 650     }
 651
 652   if (!bfd_unlock ())
 653     return false;
 654   return ret;
 655 }
 656
 657 /*
 658 FUNCTION
 659         bfd_cache_size
 660
 661 SYNOPSIS
 662         unsigned bfd_cache_size (void);
 663
 664 DESCRIPTION
 665         Return the number of open files in the cache.
 666 */
 667
 668 unsigned
 669 bfd_cache_size (void)
 670 {
 671   return open_files;
 672 }
 673
 674 static FILE *
 675 _bfd_open_file_unlocked (bfd *abfd)
 676 {
 677   abfd->cacheable = true;       /* Allow it to be closed later.  */
 678
 679   if (open_files >= bfd_cache_max_open ())
 680     {
 681       if (! close_one ())
 682         return NULL;
 683     }
 684
 685   switch (abfd->direction)
 686     {
 687     case read_direction:
 688     case no_direction:
 689       abfd->iostream = _bfd_real_fopen (bfd_get_filename (abfd), FOPEN_RB);
 690       break;
 691     case both_direction:
 692     case write_direction:
 693       if (abfd->opened_once)
 694         {
 695           abfd->iostream = _bfd_real_fopen (bfd_get_filename (abfd),
 696                                             FOPEN_RUB);
 697           if (abfd->iostream == NULL)
 698             abfd->iostream = _bfd_real_fopen (bfd_get_filename (abfd),
 699                                               FOPEN_WUB);
 700         }
 701       else
 702         {
 703           /* Create the file.
 704
 705              Some operating systems won't let us overwrite a running
 706              binary.  For them, we want to unlink the file first.
 707
 708              However, gcc 2.95 will create temporary files using
 709              O_EXCL and tight permissions to prevent other users from
 710              substituting other .o files during the compilation.  gcc
 711              will then tell the assembler to use the newly created
 712              file as an output file.  If we unlink the file here, we
 713              open a brief window when another user could still
 714              substitute a file.
 715
 716              So we unlink the output file if and only if it has
 717              non-zero size.  */
 718 #ifndef __MSDOS__
 719           /* Don't do this for MSDOS: it doesn't care about overwriting
 720              a running binary, but if this file is already open by
 721              another BFD, we will be in deep trouble if we delete an
 722              open file.  In fact, objdump does just that if invoked with
 723              the --info option.  */
 724           struct stat s;
 725
 726           if (stat (bfd_get_filename (abfd), &s) == 0 && s.st_size != 0)
 727             unlink_if_ordinary (bfd_get_filename (abfd));
 728 #endif
 729           abfd->iostream = _bfd_real_fopen (bfd_get_filename (abfd),
 730                                             FOPEN_WUB);
 731           abfd->opened_once = true;
 732         }
 733       break;
 734     }
 735
 736   if (abfd->iostream == NULL)
 737     bfd_set_error (bfd_error_system_call);
 738   else
 739     {
 740       if (! _bfd_cache_init_unlocked (abfd))
 741         return NULL;
 742     }
 743
 744   return (FILE *) abfd->iostream;
 745 }
 746
 747 /*
 748 INTERNAL_FUNCTION
 749         bfd_open_file
 750
 751 SYNOPSIS
 752         FILE* bfd_open_file (bfd *abfd);
 753
 754 DESCRIPTION
 755         Call the OS to open a file for @var{abfd}.  Return the <<FILE *>>
 756         (possibly <<NULL>>) that results from this operation.  Set up the
 757         BFD so that future accesses know the file is open. If the <<FILE *>>
 758         returned is <<NULL>>, then it won't have been put in the
 759         cache, so it won't have to be removed from it.
 760 */
 761
 762 FILE *
 763 bfd_open_file (bfd *abfd)
 764 {
 765   if (!bfd_lock ())
 766     return NULL;
 767   FILE *result = _bfd_open_file_unlocked (abfd);
 768   if (!bfd_unlock ())
 769     return NULL;
 770   return result;
 771 }