[thirdparty/binutils-gdb.git] / gdb / exec.h

/* Work with executable files, for GDB, the GNU debugger.

   Copyright (C) 2003-2025 Free Software Foundation, Inc.

   This file is part of GDB.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 3 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program.  If not, see <http://www.gnu.org/licenses/>.  */

#ifndef GDB_EXEC_H
#define GDB_EXEC_H

#include "target.h"
#include "progspace.h"
#include "memrange.h"
#include "symfile-add-flags.h"

struct target_section;
struct target_ops;
struct bfd;
struct objfile;

/* Builds a section table, given args BFD.  */

extern std::vector<target_section> build_section_table (struct bfd *);

/* VFORK_CHILD is a child vforked and its program space is shared with its
   parent.  This pushes the exec target on that inferior's target stack if
   there are sections in the program space's section table.  */

extern void exec_on_vfork (inferior *vfork_child);

/* Read from mappable read-only sections of BFD executable files.
   Return TARGET_XFER_OK, if read is successful.  Return
   TARGET_XFER_EOF if read is done.  Return TARGET_XFER_E_IO
   otherwise.  */

extern enum target_xfer_status
  exec_read_partial_read_only (gdb_byte *readbuf, ULONGEST offset,
			       ULONGEST len, ULONGEST *xfered_len);

/* Read or write from mappable sections of BFD executable files.

   Request to transfer up to LEN 8-bit bytes of the target sections
   defined by SECTIONS and SECTIONS_END.  The OFFSET specifies the
   starting address.

   The MATCH_CB predicate is optional; when provided it will be called
   for each section under consideration.  When MATCH_CB evaluates as
   true, the section remains under consideration; a false result
   removes it from consideration for performing the memory transfers
   noted above.  See memory_xfer_partial_1() in target.c for an
   example.

   Return the number of bytes actually transferred, or zero when no
   data is available for the requested range.

   This function is intended to be used from target_xfer_partial
   implementations.  See target_read and target_write for more
   information.

   One, and only one, of readbuf or writebuf must be non-NULL.  */

extern enum target_xfer_status
  section_table_xfer_memory_partial (gdb_byte *,
				     const gdb_byte *,
				     ULONGEST, ULONGEST, ULONGEST *,
				     const std::vector<target_section> &,
				     gdb::function_view<bool
				       (const struct target_section *)> match_cb
					 = nullptr);

/* Read from mappable read-only sections of BFD executable files.
   Similar to exec_read_partial_read_only, but return
   TARGET_XFER_UNAVAILABLE if data is unavailable.  */

extern enum target_xfer_status
  section_table_read_available_memory (gdb_byte *readbuf, ULONGEST offset,
				       ULONGEST len, ULONGEST *xfered_len);

/* Set the loaded address of a section.  */
extern void exec_set_section_address (const char *, int, CORE_ADDR);

/* Prints info about all sections defined in the TABLE.  ABFD is
   special cased --- it's filename is omitted; if it is the executable
   file, its entry point is printed.  */

extern void print_section_info (const std::vector<target_section> *table,
				bfd *abfd);

/* Helper function that attempts to open the symbol file at EXEC_FILE_HOST.
   If successful, it proceeds to add the symbol file as the main symbol file.

   ADD_FLAGS is passed on to the function adding the symbol file.  */
extern void try_open_exec_file (const char *exec_file_host,
				struct inferior *inf,
				symfile_add_flags add_flags);

/* Report a "No executable file specified" error.  */

extern void no_executable_specified_error ();

#endif /* GDB_EXEC_H */
Commit	Line	Data
	1	/* Work with executable files, for GDB, the GNU debugger.
	2
	3	Copyright (C) 2003-2025 Free Software Foundation, Inc.
	4
	5	This file is part of GDB.
	6
	7	This program is free software; you can redistribute it and/or modify
	8	it under the terms of the GNU General Public License as published by
	9	the Free Software Foundation; either version 3 of the License, or
	10	(at your option) any later version.
	11
	12	This program is distributed in the hope that it will be useful,
	13	but WITHOUT ANY WARRANTY; without even the implied warranty of
	14	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	15	GNU General Public License for more details.
	16
	17	You should have received a copy of the GNU General Public License
	18	along with this program. If not, see <http://www.gnu.org/licenses/>. */
	19
	20	#ifndef GDB_EXEC_H
	21	#define GDB_EXEC_H
	22
	23	#include "target.h"
	24	#include "progspace.h"
	25	#include "memrange.h"
	26	#include "symfile-add-flags.h"
	27
	28	struct target_section;
	29	struct target_ops;
	30	struct bfd;
	31	struct objfile;
	32
	33	/* Builds a section table, given args BFD. */
	34
	35	extern std::vector<target_section> build_section_table (struct bfd *);
	36
	37	/* VFORK_CHILD is a child vforked and its program space is shared with its
	38	parent. This pushes the exec target on that inferior's target stack if
	39	there are sections in the program space's section table. */
	40
	41	extern void exec_on_vfork (inferior *vfork_child);
	42
	43	/* Read from mappable read-only sections of BFD executable files.
	44	Return TARGET_XFER_OK, if read is successful. Return
	45	TARGET_XFER_EOF if read is done. Return TARGET_XFER_E_IO
	46	otherwise. */
	47
	48	extern enum target_xfer_status
	49	exec_read_partial_read_only (gdb_byte *readbuf, ULONGEST offset,
	50	ULONGEST len, ULONGEST *xfered_len);
	51
	52	/* Read or write from mappable sections of BFD executable files.
	53
	54	Request to transfer up to LEN 8-bit bytes of the target sections
	55	defined by SECTIONS and SECTIONS_END. The OFFSET specifies the
	56	starting address.
	57
	58	The MATCH_CB predicate is optional; when provided it will be called
	59	for each section under consideration. When MATCH_CB evaluates as
	60	true, the section remains under consideration; a false result
	61	removes it from consideration for performing the memory transfers
	62	noted above. See memory_xfer_partial_1() in target.c for an
	63	example.
	64
	65	Return the number of bytes actually transferred, or zero when no
	66	data is available for the requested range.
	67
	68	This function is intended to be used from target_xfer_partial
	69	implementations. See target_read and target_write for more
	70	information.
	71
	72	One, and only one, of readbuf or writebuf must be non-NULL. */
	73
	74	extern enum target_xfer_status
	75	section_table_xfer_memory_partial (gdb_byte *,
	76	const gdb_byte *,
	77	ULONGEST, ULONGEST, ULONGEST *,
	78	const std::vector<target_section> &,
	79	gdb::function_view<bool
	80	(const struct target_section *)> match_cb
	81	= nullptr);
	82
	83	/* Read from mappable read-only sections of BFD executable files.
	84	Similar to exec_read_partial_read_only, but return
	85	TARGET_XFER_UNAVAILABLE if data is unavailable. */
	86
	87	extern enum target_xfer_status
	88	section_table_read_available_memory (gdb_byte *readbuf, ULONGEST offset,
	89	ULONGEST len, ULONGEST *xfered_len);
	90
	91	/* Set the loaded address of a section. */
	92	extern void exec_set_section_address (const char *, int, CORE_ADDR);
	93
	94	/* Prints info about all sections defined in the TABLE. ABFD is
	95	special cased --- it's filename is omitted; if it is the executable
	96	file, its entry point is printed. */
	97
	98	extern void print_section_info (const std::vector<target_section> *table,
	99	bfd *abfd);
	100
	101	/* Helper function that attempts to open the symbol file at EXEC_FILE_HOST.
	102	If successful, it proceeds to add the symbol file as the main symbol file.
	103
	104	ADD_FLAGS is passed on to the function adding the symbol file. */
	105	extern void try_open_exec_file (const char *exec_file_host,
	106	struct inferior *inf,
	107	symfile_add_flags add_flags);
	108
	109	/* Report a "No executable file specified" error. */
	110
	111	extern void no_executable_specified_error ();
	112
	113	#endif /* GDB_EXEC_H */