bfd/cache.c

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