daily update
[binutils.git] / bfd / format.c
blobba9ca9f6095366cf8ed4dc81cee78b844d83493c
1 /* Generic BFD support for file formats.
2 Copyright 1990, 1991, 1992, 1993, 1994, 1995, 1999, 2000, 2001, 2002,
3 2003, 2005 Free Software Foundation, Inc.
4 Written by Cygnus Support.
6 This file is part of BFD, the Binary File Descriptor library.
8 This program is free software; you can redistribute it and/or modify
9 it under the terms of the GNU General Public License as published by
10 the Free Software Foundation; either version 2 of the License, or
11 (at your option) any later version.
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
18 You should have received a copy of the GNU General Public License
19 along with this program; if not, write to the Free Software
20 Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, USA. */
23 SECTION
24 File formats
26 A format is a BFD concept of high level file contents type. The
27 formats supported by BFD are:
29 o <<bfd_object>>
31 The BFD may contain data, symbols, relocations and debug info.
33 o <<bfd_archive>>
35 The BFD contains other BFDs and an optional index.
37 o <<bfd_core>>
39 The BFD contains the result of an executable core dump.
41 SUBSECTION
42 File format functions
45 #include "bfd.h"
46 #include "sysdep.h"
47 #include "libbfd.h"
49 /* IMPORT from targets.c. */
50 extern const size_t _bfd_target_vector_entries;
53 FUNCTION
54 bfd_check_format
56 SYNOPSIS
57 bfd_boolean bfd_check_format (bfd *abfd, bfd_format format);
59 DESCRIPTION
60 Verify if the file attached to the BFD @var{abfd} is compatible
61 with the format @var{format} (i.e., one of <<bfd_object>>,
62 <<bfd_archive>> or <<bfd_core>>).
64 If the BFD has been set to a specific target before the
65 call, only the named target and format combination is
66 checked. If the target has not been set, or has been set to
67 <<default>>, then all the known target backends is
68 interrogated to determine a match. If the default target
69 matches, it is used. If not, exactly one target must recognize
70 the file, or an error results.
72 The function returns <<TRUE>> on success, otherwise <<FALSE>>
73 with one of the following error codes:
75 o <<bfd_error_invalid_operation>> -
76 if <<format>> is not one of <<bfd_object>>, <<bfd_archive>> or
77 <<bfd_core>>.
79 o <<bfd_error_system_call>> -
80 if an error occured during a read - even some file mismatches
81 can cause bfd_error_system_calls.
83 o <<file_not_recognised>> -
84 none of the backends recognised the file format.
86 o <<bfd_error_file_ambiguously_recognized>> -
87 more than one backend recognised the file format.
90 bfd_boolean
91 bfd_check_format (bfd *abfd, bfd_format format)
93 return bfd_check_format_matches (abfd, format, NULL);
97 FUNCTION
98 bfd_check_format_matches
100 SYNOPSIS
101 bfd_boolean bfd_check_format_matches
102 (bfd *abfd, bfd_format format, char ***matching);
104 DESCRIPTION
105 Like <<bfd_check_format>>, except when it returns FALSE with
106 <<bfd_errno>> set to <<bfd_error_file_ambiguously_recognized>>. In that
107 case, if @var{matching} is not NULL, it will be filled in with
108 a NULL-terminated list of the names of the formats that matched,
109 allocated with <<malloc>>.
110 Then the user may choose a format and try again.
112 When done with the list that @var{matching} points to, the caller
113 should free it.
116 bfd_boolean
117 bfd_check_format_matches (bfd *abfd, bfd_format format, char ***matching)
119 extern const bfd_target binary_vec;
120 const bfd_target * const *target;
121 const bfd_target **matching_vector = NULL;
122 const bfd_target *save_targ, *right_targ, *ar_right_targ;
123 int match_count;
124 int ar_match_index;
126 if (!bfd_read_p (abfd)
127 || (unsigned int) abfd->format >= (unsigned int) bfd_type_end)
129 bfd_set_error (bfd_error_invalid_operation);
130 return FALSE;
133 if (abfd->format != bfd_unknown)
134 return abfd->format == format;
136 /* Since the target type was defaulted, check them
137 all in the hope that one will be uniquely recognized. */
138 save_targ = abfd->xvec;
139 match_count = 0;
140 ar_match_index = _bfd_target_vector_entries;
142 if (matching)
144 bfd_size_type amt;
146 *matching = NULL;
147 amt = sizeof (*matching_vector) * 2 * _bfd_target_vector_entries;
148 matching_vector = bfd_malloc (amt);
149 if (!matching_vector)
150 return FALSE;
153 right_targ = 0;
154 ar_right_targ = 0;
156 /* Presume the answer is yes. */
157 abfd->format = format;
159 /* If the target type was explicitly specified, just check that target. */
160 if (!abfd->target_defaulted)
162 if (bfd_seek (abfd, (file_ptr) 0, SEEK_SET) != 0) /* rewind! */
164 if (matching)
165 free (matching_vector);
166 return FALSE;
169 right_targ = BFD_SEND_FMT (abfd, _bfd_check_format, (abfd));
171 if (right_targ)
173 abfd->xvec = right_targ; /* Set the target as returned. */
175 if (matching)
176 free (matching_vector);
178 /* If the file was opened for update, then `output_has_begun'
179 some time ago when the file was created. Do not recompute
180 sections sizes or alignments in _bfd_set_section_contents.
181 We can not set this flag until after checking the format,
182 because it will interfere with creation of BFD sections. */
183 if (abfd->direction == both_direction)
184 abfd->output_has_begun = TRUE;
186 return TRUE; /* File position has moved, BTW. */
189 /* For a long time the code has dropped through to check all
190 targets if the specified target was wrong. I don't know why,
191 and I'm reluctant to change it. However, in the case of an
192 archive, it can cause problems. If the specified target does
193 not permit archives (e.g., the binary target), then we should
194 not allow some other target to recognize it as an archive, but
195 should instead allow the specified target to recognize it as an
196 object. When I first made this change, it broke the PE target,
197 because the specified pei-i386 target did not recognize the
198 actual pe-i386 archive. Since there may be other problems of
199 this sort, I changed this test to check only for the binary
200 target. */
201 if (format == bfd_archive && save_targ == &binary_vec)
203 abfd->xvec = save_targ;
204 abfd->format = bfd_unknown;
206 if (matching)
207 free (matching_vector);
209 bfd_set_error (bfd_error_file_not_recognized);
211 return FALSE;
215 for (target = bfd_target_vector; *target != NULL; target++)
217 const bfd_target *temp;
218 bfd_error_type err;
220 if (*target == &binary_vec)
221 continue;
223 abfd->xvec = *target; /* Change BFD's target temporarily. */
225 if (bfd_seek (abfd, (file_ptr) 0, SEEK_SET) != 0)
227 if (matching)
228 free (matching_vector);
229 return FALSE;
232 /* If _bfd_check_format neglects to set bfd_error, assume
233 bfd_error_wrong_format. We didn't used to even pay any
234 attention to bfd_error, so I suspect that some
235 _bfd_check_format might have this problem. */
236 bfd_set_error (bfd_error_wrong_format);
238 temp = BFD_SEND_FMT (abfd, _bfd_check_format, (abfd));
240 if (temp)
242 /* This format checks out as ok! */
243 right_targ = temp;
245 /* If this is the default target, accept it, even if other
246 targets might match. People who want those other targets
247 have to set the GNUTARGET variable. */
248 if (temp == bfd_default_vector[0])
250 match_count = 1;
251 break;
254 if (matching)
255 matching_vector[match_count] = temp;
257 match_count++;
259 else if ((err = bfd_get_error ()) == bfd_error_wrong_object_format
260 || err == bfd_error_file_ambiguously_recognized)
262 /* An archive with objects of the wrong type, or an
263 ambiguous match. We want this target to match if we get
264 no better matches. */
265 if (ar_right_targ != bfd_default_vector[0])
266 ar_right_targ = *target;
267 if (matching)
268 matching_vector[ar_match_index] = *target;
269 ar_match_index++;
271 else if (err != bfd_error_wrong_format)
273 abfd->xvec = save_targ;
274 abfd->format = bfd_unknown;
276 if (matching)
277 free (matching_vector);
279 return FALSE;
283 if (match_count == 0)
285 /* Try partial matches. */
286 right_targ = ar_right_targ;
288 if (right_targ == bfd_default_vector[0])
290 match_count = 1;
292 else
294 match_count = ar_match_index - _bfd_target_vector_entries;
296 if (matching && match_count > 1)
297 memcpy (matching_vector,
298 matching_vector + _bfd_target_vector_entries,
299 sizeof (*matching_vector) * match_count);
303 if (match_count > 1
304 && bfd_associated_vector != NULL
305 && matching)
307 const bfd_target * const *assoc = bfd_associated_vector;
309 while ((right_targ = *assoc++) != NULL)
311 int i = match_count;
313 while (--i >= 0)
314 if (matching_vector[i] == right_targ)
315 break;
317 if (i >= 0)
319 match_count = 1;
320 break;
325 if (match_count == 1)
327 abfd->xvec = right_targ; /* Change BFD's target permanently. */
329 if (matching)
330 free (matching_vector);
332 /* If the file was opened for update, then `output_has_begun'
333 some time ago when the file was created. Do not recompute
334 sections sizes or alignments in _bfd_set_section_contents.
335 We can not set this flag until after checking the format,
336 because it will interfere with creation of BFD sections. */
337 if (abfd->direction == both_direction)
338 abfd->output_has_begun = TRUE;
340 return TRUE; /* File position has moved, BTW. */
343 abfd->xvec = save_targ; /* Restore original target type. */
344 abfd->format = bfd_unknown; /* Restore original format. */
346 if (match_count == 0)
348 bfd_set_error (bfd_error_file_not_recognized);
350 if (matching)
351 free (matching_vector);
353 else
355 bfd_set_error (bfd_error_file_ambiguously_recognized);
357 if (matching)
359 *matching = (char **) matching_vector;
360 matching_vector[match_count] = NULL;
361 /* Return target names. This is a little nasty. Maybe we
362 should do another bfd_malloc? */
363 while (--match_count >= 0)
365 const char *name = matching_vector[match_count]->name;
366 *(const char **) &matching_vector[match_count] = name;
371 return FALSE;
375 FUNCTION
376 bfd_set_format
378 SYNOPSIS
379 bfd_boolean bfd_set_format (bfd *abfd, bfd_format format);
381 DESCRIPTION
382 This function sets the file format of the BFD @var{abfd} to the
383 format @var{format}. If the target set in the BFD does not
384 support the format requested, the format is invalid, or the BFD
385 is not open for writing, then an error occurs.
388 bfd_boolean
389 bfd_set_format (bfd *abfd, bfd_format format)
391 if (bfd_read_p (abfd)
392 || (unsigned int) abfd->format >= (unsigned int) bfd_type_end)
394 bfd_set_error (bfd_error_invalid_operation);
395 return FALSE;
398 if (abfd->format != bfd_unknown)
399 return abfd->format == format;
401 /* Presume the answer is yes. */
402 abfd->format = format;
404 if (!BFD_SEND_FMT (abfd, _bfd_set_format, (abfd)))
406 abfd->format = bfd_unknown;
407 return FALSE;
410 return TRUE;
414 FUNCTION
415 bfd_format_string
417 SYNOPSIS
418 const char *bfd_format_string (bfd_format format);
420 DESCRIPTION
421 Return a pointer to a const string
422 <<invalid>>, <<object>>, <<archive>>, <<core>>, or <<unknown>>,
423 depending upon the value of @var{format}.
426 const char *
427 bfd_format_string (bfd_format format)
429 if (((int) format < (int) bfd_unknown)
430 || ((int) format >= (int) bfd_type_end))
431 return "invalid";
433 switch (format)
435 case bfd_object:
436 return "object"; /* Linker/assembler/compiler output. */
437 case bfd_archive:
438 return "archive"; /* Object archive file. */
439 case bfd_core:
440 return "core"; /* Core dump. */
441 default:
442 return "unknown";