From 93351e91c53c3a4dcc69950f6542c2e7788d7851 Mon Sep 17 00:00:00 2001 From: Steve Chamberlain Date: Sat, 30 Nov 1991 22:33:57 +0000 Subject: [PATCH] Even more documentation --- bfd/bfd.c | 313 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 163 insertions(+), 150 deletions(-) diff --git a/bfd/bfd.c b/bfd/bfd.c index 1e6d49b4c3b..d47a528030d 100644 --- a/bfd/bfd.c +++ b/bfd/bfd.c @@ -20,142 +20,143 @@ Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ /* $Id$ */ -/*proto* -@section @code{typedef bfd} +/* +SECTION + <> -A BFD is has type @code{bfd}; objects of this type are the cornerstone -of any application using @code{libbfd}. References though the BFD and -to data in the BFD give the entire BFD functionality. +DESCRIPTION + A BFD is has type <>; objects of this type are the + cornerstone of any application using <>. References + though the BFD and to data in the BFD give the entire BFD + functionality. -Here is the struct used to define the type @code{bfd}. This contains -the major data about the file, and contains pointers to the rest of -the data. + Here is the struct used to define the type <>. This + contains he major data about the file, and contains pointers + to the rest of the data. -*+++ +.struct _bfd +.{ + The filename the application opened the BFD with. -$struct _bfd -${ - The filename the application opened the BFD with. +. CONST char *filename; -$ CONST char *filename; + A pointer to the target jump table. -A pointer to the target jump table. +. struct bfd_target *xvec; -$ struct bfd_target *xvec; + To avoid dragging too many header files into every file that + includes @file{bfd.h}, IOSTREAM has been declared as a "char + *", and MTIME as a "long". Their correct types, to which they + are cast when used, are "FILE *" and "time_t". The iostream + is the result of an fopen on the filename. - -To avoid dragging too many header files into every file that -includes @file{bfd.h}, IOSTREAM has been declared as a "char *", and MTIME -as a "long". Their correct types, to which they are cast when used, -are "FILE *" and "time_t". - -The iostream is the result of an fopen on the filename. - -$ char *iostream; +. char *iostream; Is the file being cached @xref{File Caching}. -$ boolean cacheable; +. boolean cacheable; + + Marks whether there was a default target specified when the + BFD was opened. This is used to select what matching algorithm + to use to chose the back end. -Marks whether there was a default target specified when the BFD was -opened. This is used to select what matching algorithm to use to chose -the back end. +. boolean target_defaulted; -$ boolean target_defaulted; + The caching routines use these to maintain a + least-recently-used list of BFDs (@pxref{File Caching}). -The caching routines use these to maintain a least-recently-used list of -BFDs (@pxref{File Caching}). +. struct _bfd *lru_prev, *lru_next; -$ struct _bfd *lru_prev, *lru_next; + When a file is closed by the caching routines, BFD retains + state information on the file here: -When a file is closed by the caching routines, BFD retains state -information on the file here: +. file_ptr where; -$ file_ptr where; + and here: -and here: +. boolean opened_once; -$ boolean opened_once; +. boolean mtime_set; -$ boolean mtime_set; File modified time -$ long mtime; +. long mtime; -Reserved for an unimplemented file locking extension. + Reserved for an unimplemented file locking extension. -$int ifd; +. int ifd; -The format which belongs to the BFD. + The format which belongs to the BFD. -$ bfd_format format; +. bfd_format format; -The direction the BFD was opened with + The direction the BFD was opened with -$ enum bfd_direction {no_direction = 0, -$ read_direction = 1, -$ write_direction = 2, -$ both_direction = 3} direction; +. enum bfd_direction {no_direction = 0, +. read_direction = 1, +. write_direction = 2, +. both_direction = 3} direction; -Format_specific flags + Format_specific flags -$ flagword flags; +. flagword flags; -Currently my_archive is tested before adding origin to anything. I -believe that this can become always an add of origin, with origin set -to 0 for non archive files. + Currently my_archive is tested before adding origin to + anything. I believe that this can become always an add of + origin, with origin set to 0 for non archive files. -$ file_ptr origin; +. file_ptr origin; -Remember when output has begun, to stop strange things happening. + Remember when output has begun, to stop strange things happening. -$ boolean output_has_begun; +. boolean output_has_begun; -Pointer to linked list of sections + Pointer to linked list of sections -$ struct sec *sections; +. struct sec *sections; -The number of sections + The number of sections -$ unsigned int section_count; +. unsigned int section_count; -Stuff only useful for object files: -The start address. + Stuff only useful for object files: + The start address. -$ bfd_vma start_address; -Used for input and output +. bfd_vma start_address; -$ unsigned int symcount; -Symbol table for output BFD + Used for input and output -$ struct symbol_cache_entry **outsymbols; +. unsigned int symcount; -Pointer to structure which contains architecture information + Symbol table for output BFD -$ struct bfd_arch_info *arch_info; +. struct symbol_cache_entry **outsymbols; -Stuff only useful for archives: + Pointer to structure which contains architecture information -$ PTR arelt_data; -$ struct _bfd *my_archive; -$ struct _bfd *next; -$ struct _bfd *archive_head; -$ boolean has_armap; +. struct bfd_arch_info *arch_info; -Used by the back end to hold private data. + Stuff only useful for archives: -$ PTR tdata; +. PTR arelt_data; +. struct _bfd *my_archive; +. struct _bfd *next; +. struct _bfd *archive_head; +. boolean has_armap; -Used by the application to hold private data + Used by the back end to hold private data. -$ PTR usrdata; +. PTR tdata; -Where all the allocated stuff under this BFD goes (@pxref{Memory Usage}). + Used by the application to hold private data -$ struct obstack memory; -$}; +. PTR usrdata; -*--- + Where all the allocated stuff under this BFD goes + (@pxref{Memory Usage}). + +. struct obstack memory; +.}; */ #include "bfd.h" @@ -338,12 +339,19 @@ int line; } -/*proto* bfd_set_start_address +/* +FUNCTION + bfd_set_start_address + +DESCRIPTION + + Marks the entry point of an output BFD. -Marks the entry point of an output BFD. Returns @code{true} on -success, @code{false} otherwise. +RETURNS + Returns <> on success, <> otherwise. -*; PROTO(boolean, bfd_set_start_address,(bfd *, bfd_vma)); +SYNOPSIS + boolean bfd_set_start_address(bfd *, bfd_vma); */ boolean @@ -356,14 +364,18 @@ bfd_vma vma; } -/*proto* bfd_get_mtime +/* +FUNCTION + bfd_get_mtime -Return cached file modification time (e.g. as read from archive header -for archive members, or from file system if we have been called -before); else determine modify time, cache it, and return it. - -*; PROTO(long, bfd_get_mtime, (bfd *)); +DESCRIPTION + Return cached file modification time (e.g. as read from + archive header for archive members, or from file system if we + have been called before); else determine modify time, cache + it, and return it. +SYNOPSIS + long bfd_get_mtime(bfd *); */ long @@ -385,63 +397,64 @@ bfd_get_mtime (abfd) return abfd->mtime; } -/*proto* stuff - -*+ - -#define bfd_sizeof_headers(abfd, reloc) \ - BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, reloc)) - -#define bfd_find_nearest_line(abfd, section, symbols, offset, filename_ptr, func, line_ptr) \ - BFD_SEND (abfd, _bfd_find_nearest_line, (abfd, section, symbols, offset, filename_ptr, func, line_ptr)) - -#define bfd_debug_info_start(abfd) \ - BFD_SEND (abfd, _bfd_debug_info_start, (abfd)) - -#define bfd_debug_info_end(abfd) \ - BFD_SEND (abfd, _bfd_debug_info_end, (abfd)) - -#define bfd_debug_info_accumulate(abfd, section) \ - BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section)) - -#define bfd_stat_arch_elt(abfd, stat) \ - BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat)) - -#define bfd_coff_swap_aux_in(a,e,t,c,i) \ - BFD_SEND (a, _bfd_coff_swap_aux_in, (a,e,t,c,i)) - -#define bfd_coff_swap_sym_in(a,e,i) \ - BFD_SEND (a, _bfd_coff_swap_sym_in, (a,e,i)) - -#define bfd_coff_swap_lineno_in(a,e,i) \ - BFD_SEND ( a, _bfd_coff_swap_lineno_in, (a,e,i)) - -#define bfd_set_arch_mach(abfd, arch, mach)\ - BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach)) - -#define bfd_coff_swap_reloc_out(abfd, i, o) \ - BFD_SEND (abfd, _bfd_coff_swap_reloc_out, (abfd, i, o)) - -#define bfd_coff_swap_lineno_out(abfd, i, o) \ - BFD_SEND (abfd, _bfd_coff_swap_lineno_out, (abfd, i, o)) - -#define bfd_coff_swap_aux_out(abfd, i, t,c,o) \ - BFD_SEND (abfd, _bfd_coff_swap_aux_out, (abfd, i,t,c, o)) - -#define bfd_coff_swap_sym_out(abfd, i,o) \ - BFD_SEND (abfd, _bfd_coff_swap_sym_out, (abfd, i, o)) - -#define bfd_coff_swap_scnhdr_out(abfd, i,o) \ - BFD_SEND (abfd, _bfd_coff_swap_scnhdr_out, (abfd, i, o)) - -#define bfd_coff_swap_filehdr_out(abfd, i,o) \ - BFD_SEND (abfd, _bfd_coff_swap_filehdr_out, (abfd, i, o)) - -#define bfd_coff_swap_aouthdr_out(abfd, i,o) \ - BFD_SEND (abfd, _bfd_coff_swap_aouthdr_out, (abfd, i, o)) - -*- - +/* +FUNCTION + stuff + +DESCRIPTION + stuff which should be documented + +.#define bfd_sizeof_headers(abfd, reloc) \ +. BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, reloc)) +. +.#define bfd_find_nearest_line(abfd, section, symbols, offset, filename_ptr, func, line_ptr) \ +. BFD_SEND (abfd, _bfd_find_nearest_line, (abfd, section, symbols, offset, filename_ptr, func, line_ptr)) +. +.#define bfd_debug_info_start(abfd) \ +. BFD_SEND (abfd, _bfd_debug_info_start, (abfd)) +. +.#define bfd_debug_info_end(abfd) \ +. BFD_SEND (abfd, _bfd_debug_info_end, (abfd)) +. +.#define bfd_debug_info_accumulate(abfd, section) \ +. BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section)) +. +.#define bfd_stat_arch_elt(abfd, stat) \ +. BFD_SEND (abfd, _bfd_stat_arch_elt,(abfd, stat)) +. +.#define bfd_coff_swap_aux_in(a,e,t,c,i) \ +. BFD_SEND (a, _bfd_coff_swap_aux_in, (a,e,t,c,i)) +. +.#define bfd_coff_swap_sym_in(a,e,i) \ +. BFD_SEND (a, _bfd_coff_swap_sym_in, (a,e,i)) +. +.#define bfd_coff_swap_lineno_in(a,e,i) \ +. BFD_SEND ( a, _bfd_coff_swap_lineno_in, (a,e,i)) +. +.#define bfd_set_arch_mach(abfd, arch, mach)\ +. BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach)) +. +.#define bfd_coff_swap_reloc_out(abfd, i, o) \ +. BFD_SEND (abfd, _bfd_coff_swap_reloc_out, (abfd, i, o)) +. +.#define bfd_coff_swap_lineno_out(abfd, i, o) \ +. BFD_SEND (abfd, _bfd_coff_swap_lineno_out, (abfd, i, o)) +. +.#define bfd_coff_swap_aux_out(abfd, i, t,c,o) \ +. BFD_SEND (abfd, _bfd_coff_swap_aux_out, (abfd, i,t,c, o)) +. +.#define bfd_coff_swap_sym_out(abfd, i,o) \ +. BFD_SEND (abfd, _bfd_coff_swap_sym_out, (abfd, i, o)) +. +.#define bfd_coff_swap_scnhdr_out(abfd, i,o) \ +. BFD_SEND (abfd, _bfd_coff_swap_scnhdr_out, (abfd, i, o)) +. +.#define bfd_coff_swap_filehdr_out(abfd, i,o) \ +. BFD_SEND (abfd, _bfd_coff_swap_filehdr_out, (abfd, i, o)) +. +.#define bfd_coff_swap_aouthdr_out(abfd, i,o) \ +. BFD_SEND (abfd, _bfd_coff_swap_aouthdr_out, (abfd, i, o)) +. */ -- 2.30.2