[thirdparty/gcc.git] / libbacktrace / internal.h

/* internal.h -- Internal header file for stack backtrace library.
   Copyright (C) 2012-2021 Free Software Foundation, Inc.
   Written by Ian Lance Taylor, Google.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

    (1) Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.

    (2) Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in
    the documentation and/or other materials provided with the
    distribution.

    (3) The name of the author may not be used to
    endorse or promote products derived from this software without
    specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.  */

#ifndef BACKTRACE_INTERNAL_H
#define BACKTRACE_INTERNAL_H

/* We assume that <sys/types.h> and "backtrace.h" have already been
   included.  */

#ifndef GCC_VERSION
# define GCC_VERSION (__GNUC__ * 1000 + __GNUC_MINOR__)
#endif

#if (GCC_VERSION < 2007)
# define __attribute__(x)
#endif

#ifndef ATTRIBUTE_UNUSED
# define ATTRIBUTE_UNUSED __attribute__ ((__unused__))
#endif

#ifndef ATTRIBUTE_MALLOC
# if (GCC_VERSION >= 2096)
#  define ATTRIBUTE_MALLOC __attribute__ ((__malloc__))
# else
#  define ATTRIBUTE_MALLOC
# endif
#endif

#ifndef ATTRIBUTE_FALLTHROUGH
# if (GCC_VERSION >= 7000)
#  define ATTRIBUTE_FALLTHROUGH __attribute__ ((__fallthrough__))
# else
#  define ATTRIBUTE_FALLTHROUGH
# endif
#endif

#ifndef HAVE_SYNC_FUNCTIONS

/* Define out the sync functions.  These should never be called if
   they are not available.  */

#define __sync_bool_compare_and_swap(A, B, C) (abort(), 1)
#define __sync_lock_test_and_set(A, B) (abort(), 0)
#define __sync_lock_release(A) abort()

#endif /* !defined (HAVE_SYNC_FUNCTIONS) */

#ifdef HAVE_ATOMIC_FUNCTIONS

/* We have the atomic builtin functions.  */

#define backtrace_atomic_load_pointer(p) \
    __atomic_load_n ((p), __ATOMIC_ACQUIRE)
#define backtrace_atomic_load_int(p) \
    __atomic_load_n ((p), __ATOMIC_ACQUIRE)
#define backtrace_atomic_store_pointer(p, v) \
    __atomic_store_n ((p), (v), __ATOMIC_RELEASE)
#define backtrace_atomic_store_size_t(p, v) \
    __atomic_store_n ((p), (v), __ATOMIC_RELEASE)
#define backtrace_atomic_store_int(p, v) \
    __atomic_store_n ((p), (v), __ATOMIC_RELEASE)

#else /* !defined (HAVE_ATOMIC_FUNCTIONS) */
#ifdef HAVE_SYNC_FUNCTIONS

/* We have the sync functions but not the atomic functions.  Define
   the atomic ones in terms of the sync ones.  */

extern void *backtrace_atomic_load_pointer (void *);
extern int backtrace_atomic_load_int (int *);
extern void backtrace_atomic_store_pointer (void *, void *);
extern void backtrace_atomic_store_size_t (size_t *, size_t);
extern void backtrace_atomic_store_int (int *, int);

#else /* !defined (HAVE_SYNC_FUNCTIONS) */

/* We have neither the sync nor the atomic functions.  These will
   never be called.  */

#define backtrace_atomic_load_pointer(p) (abort(), (void *) NULL)
#define backtrace_atomic_load_int(p) (abort(), 0)
#define backtrace_atomic_store_pointer(p, v) abort()
#define backtrace_atomic_store_size_t(p, v) abort()
#define backtrace_atomic_store_int(p, v) abort()

#endif /* !defined (HAVE_SYNC_FUNCTIONS) */
#endif /* !defined (HAVE_ATOMIC_FUNCTIONS) */

/* The type of the function that collects file/line information.  This
   is like backtrace_pcinfo.  */

typedef int (*fileline) (struct backtrace_state *state, uintptr_t pc,
			 backtrace_full_callback callback,
			 backtrace_error_callback error_callback, void *data);

/* The type of the function that collects symbol information.  This is
   like backtrace_syminfo.  */

typedef void (*syminfo) (struct backtrace_state *state, uintptr_t pc,
			 backtrace_syminfo_callback callback,
			 backtrace_error_callback error_callback, void *data);

/* What the backtrace state pointer points to.  */

struct backtrace_state
{
  /* The name of the executable.  */
  const char *filename;
  /* Non-zero if threaded.  */
  int threaded;
  /* The master lock for fileline_fn, fileline_data, syminfo_fn,
     syminfo_data, fileline_initialization_failed and everything the
     data pointers point to.  */
  void *lock;
  /* The function that returns file/line information.  */
  fileline fileline_fn;
  /* The data to pass to FILELINE_FN.  */
  void *fileline_data;
  /* The function that returns symbol information.  */
  syminfo syminfo_fn;
  /* The data to pass to SYMINFO_FN.  */
  void *syminfo_data;
  /* Whether initializing the file/line information failed.  */
  int fileline_initialization_failed;
  /* The lock for the freelist.  */
  int lock_alloc;
  /* The freelist when using mmap.  */
  struct backtrace_freelist_struct *freelist;
};

/* Open a file for reading.  Returns -1 on error.  If DOES_NOT_EXIST
   is not NULL, *DOES_NOT_EXIST will be set to 0 normally and set to 1
   if the file does not exist.  If the file does not exist and
   DOES_NOT_EXIST is not NULL, the function will return -1 and will
   not call ERROR_CALLBACK.  On other errors, or if DOES_NOT_EXIST is
   NULL, the function will call ERROR_CALLBACK before returning.  */
extern int backtrace_open (const char *filename,
			   backtrace_error_callback error_callback,
			   void *data,
			   int *does_not_exist);

/* A view of the contents of a file.  This supports mmap when
   available.  A view will remain in memory even after backtrace_close
   is called on the file descriptor from which the view was
   obtained.  */

struct backtrace_view
{
  /* The data that the caller requested.  */
  const void *data;
  /* The base of the view.  */
  void *base;
  /* The total length of the view.  */
  size_t len;
};

/* Create a view of SIZE bytes from DESCRIPTOR at OFFSET.  Store the
   result in *VIEW.  Returns 1 on success, 0 on error.  */
extern int backtrace_get_view (struct backtrace_state *state, int descriptor,
			       off_t offset, uint64_t size,
			       backtrace_error_callback error_callback,
			       void *data, struct backtrace_view *view);

/* Release a view created by backtrace_get_view.  */
extern void backtrace_release_view (struct backtrace_state *state,
				    struct backtrace_view *view,
				    backtrace_error_callback error_callback,
				    void *data);

/* Close a file opened by backtrace_open.  Returns 1 on success, 0 on
   error.  */

extern int backtrace_close (int descriptor,
			    backtrace_error_callback error_callback,
			    void *data);

/* Sort without using memory.  */

extern void backtrace_qsort (void *base, size_t count, size_t size,
			     int (*compar) (const void *, const void *));

/* Allocate memory.  This is like malloc.  If ERROR_CALLBACK is NULL,
   this does not report an error, it just returns NULL.  */

extern void *backtrace_alloc (struct backtrace_state *state, size_t size,
			      backtrace_error_callback error_callback,
			      void *data) ATTRIBUTE_MALLOC;

/* Free memory allocated by backtrace_alloc.  If ERROR_CALLBACK is
   NULL, this does not report an error.  */

extern void backtrace_free (struct backtrace_state *state, void *mem,
			    size_t size,
			    backtrace_error_callback error_callback,
			    void *data);

/* A growable vector of some struct.  This is used for more efficient
   allocation when we don't know the final size of some group of data
   that we want to represent as an array.  */

struct backtrace_vector
{
  /* The base of the vector.  */
  void *base;
  /* The number of bytes in the vector.  */
  size_t size;
  /* The number of bytes available at the current allocation.  */
  size_t alc;
};

/* Grow VEC by SIZE bytes.  Return a pointer to the newly allocated
   bytes.  Note that this may move the entire vector to a new memory
   location.  Returns NULL on failure.  */

extern void *backtrace_vector_grow (struct backtrace_state *state, size_t size,
				    backtrace_error_callback error_callback,
				    void *data,
				    struct backtrace_vector *vec);

/* Finish the current allocation on VEC.  Prepare to start a new
   allocation.  The finished allocation will never be freed.  Returns
   a pointer to the base of the finished entries, or NULL on
   failure.  */

extern void* backtrace_vector_finish (struct backtrace_state *state,
				      struct backtrace_vector *vec,
				      backtrace_error_callback error_callback,
				      void *data);

/* Release any extra space allocated for VEC.  This may change
   VEC->base.  Returns 1 on success, 0 on failure.  */

extern int backtrace_vector_release (struct backtrace_state *state,
				     struct backtrace_vector *vec,
				     backtrace_error_callback error_callback,
				     void *data);

/* Free the space managed by VEC.  This will reset VEC.  */

static inline void
backtrace_vector_free (struct backtrace_state *state,
		       struct backtrace_vector *vec,
		       backtrace_error_callback error_callback, void *data)
{
  vec->alc += vec->size;
  vec->size = 0;
  backtrace_vector_release (state, vec, error_callback, data);
}

/* Read initial debug data from a descriptor, and set the
   fileline_data, syminfo_fn, and syminfo_data fields of STATE.
   Return the fileln_fn field in *FILELN_FN--this is done this way so
   that the synchronization code is only implemented once.  This is
   called after the descriptor has first been opened.  It will close
   the descriptor if it is no longer needed.  Returns 1 on success, 0
   on error.  There will be multiple implementations of this function,
   for different file formats.  Each system will compile the
   appropriate one.  */

extern int backtrace_initialize (struct backtrace_state *state,
				 const char *filename,
				 int descriptor,
				 backtrace_error_callback error_callback,
				 void *data,
				 fileline *fileline_fn);

/* An enum for the DWARF sections we care about.  */

enum dwarf_section
{
  DEBUG_INFO,
  DEBUG_LINE,
  DEBUG_ABBREV,
  DEBUG_RANGES,
  DEBUG_STR,
  DEBUG_ADDR,
  DEBUG_STR_OFFSETS,
  DEBUG_LINE_STR,
  DEBUG_RNGLISTS,

  DEBUG_MAX
};

/* Data for the DWARF sections we care about.  */

struct dwarf_sections
{
  const unsigned char *data[DEBUG_MAX];
  size_t size[DEBUG_MAX];
};

/* DWARF data read from a file, used for .gnu_debugaltlink.  */

struct dwarf_data;

/* Add file/line information for a DWARF module.  */

extern int backtrace_dwarf_add (struct backtrace_state *state,
				uintptr_t base_address,
				const struct dwarf_sections *dwarf_sections,
				int is_bigendian,
				struct dwarf_data *fileline_altlink,
				backtrace_error_callback error_callback,
				void *data, fileline *fileline_fn,
				struct dwarf_data **fileline_entry);

/* A data structure to pass to backtrace_syminfo_to_full.  */

struct backtrace_call_full
{
  backtrace_full_callback full_callback;
  backtrace_error_callback full_error_callback;
  void *full_data;
  int ret;
};

/* A backtrace_syminfo_callback that can call into a
   backtrace_full_callback, used when we have a symbol table but no
   debug info.  */

extern void backtrace_syminfo_to_full_callback (void *data, uintptr_t pc,
						const char *symname,
						uintptr_t symval,
						uintptr_t symsize);

/* An error callback that corresponds to
   backtrace_syminfo_to_full_callback.  */

extern void backtrace_syminfo_to_full_error_callback (void *, const char *,
						      int);

/* A test-only hook for elf_uncompress_zdebug.  */

extern int backtrace_uncompress_zdebug (struct backtrace_state *,
					const unsigned char *compressed,
					size_t compressed_size,
					backtrace_error_callback, void *data,
					unsigned char **uncompressed,
					size_t *uncompressed_size);

/* A test-only hook for elf_uncompress_lzma.  */

extern int backtrace_uncompress_lzma (struct backtrace_state *,
				      const unsigned char *compressed,
				      size_t compressed_size,
				      backtrace_error_callback, void *data,
				      unsigned char **uncompressed,
				      size_t *uncompressed_size);

#endif
Commit	Line	Data
eff02e4f	1	/* internal.h -- Internal header file for stack backtrace library.
99dee823	2	Copyright (C) 2012-2021 Free Software Foundation, Inc.
eff02e4f ILT	3	Written by Ian Lance Taylor, Google.
	4
	5	Redistribution and use in source and binary forms, with or without
	6	modification, are permitted provided that the following conditions are
	7	met:
	8
	9	(1) Redistributions of source code must retain the above copyright
84ebf639	10	notice, this list of conditions and the following disclaimer.
eff02e4f ILT	11
	12	(2) Redistributions in binary form must reproduce the above copyright
	13	notice, this list of conditions and the following disclaimer in
	14	the documentation and/or other materials provided with the
84ebf639 CL	15	distribution.
84ebf639 CL	16
eff02e4f ILT	17	(3) The name of the author may not be used to
	18	endorse or promote products derived from this software without
	19	specific prior written permission.
	20
	21	THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
	22	IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
	23	WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
	24	DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
	25	INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
	26	(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
	27	SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	28	HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
	29	STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
	30	IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
	31	POSSIBILITY OF SUCH DAMAGE. */
	32
	33	#ifndef BACKTRACE_INTERNAL_H
	34	#define BACKTRACE_INTERNAL_H
	35
	36	/* We assume that <sys/types.h> and "backtrace.h" have already been
	37	included. */
	38
	39	#ifndef GCC_VERSION
	40	# define GCC_VERSION (__GNUC__ * 1000 + __GNUC_MINOR__)
	41	#endif
	42
	43	#if (GCC_VERSION < 2007)
	44	# define __attribute__(x)
	45	#endif
	46
	47	#ifndef ATTRIBUTE_UNUSED
	48	# define ATTRIBUTE_UNUSED __attribute__ ((__unused__))
	49	#endif
	50
	51	#ifndef ATTRIBUTE_MALLOC
	52	# if (GCC_VERSION >= 2096)
	53	# define ATTRIBUTE_MALLOC __attribute__ ((__malloc__))
	54	# else
	55	# define ATTRIBUTE_MALLOC
	56	# endif
	57	#endif
	58
d962ef77 ILT	59	#ifndef ATTRIBUTE_FALLTHROUGH
	60	# if (GCC_VERSION >= 7000)
	61	# define ATTRIBUTE_FALLTHROUGH __attribute__ ((__fallthrough__))
	62	# else
	63	# define ATTRIBUTE_FALLTHROUGH
	64	# endif
	65	#endif
	66
eff02e4f ILT	67	#ifndef HAVE_SYNC_FUNCTIONS
	68
	69	/* Define out the sync functions. These should never be called if
	70	they are not available. */
	71
	72	#define __sync_bool_compare_and_swap(A, B, C) (abort(), 1)
	73	#define __sync_lock_test_and_set(A, B) (abort(), 0)
	74	#define __sync_lock_release(A) abort()
	75
49579c7e ILT	76	#endif /* !defined (HAVE_SYNC_FUNCTIONS) */
	77
	78	#ifdef HAVE_ATOMIC_FUNCTIONS
	79
	80	/* We have the atomic builtin functions. */
	81
	82	#define backtrace_atomic_load_pointer(p) \
	83	__atomic_load_n ((p), __ATOMIC_ACQUIRE)
	84	#define backtrace_atomic_load_int(p) \
	85	__atomic_load_n ((p), __ATOMIC_ACQUIRE)
	86	#define backtrace_atomic_store_pointer(p, v) \
	87	__atomic_store_n ((p), (v), __ATOMIC_RELEASE)
	88	#define backtrace_atomic_store_size_t(p, v) \
	89	__atomic_store_n ((p), (v), __ATOMIC_RELEASE)
	90	#define backtrace_atomic_store_int(p, v) \
	91	__atomic_store_n ((p), (v), __ATOMIC_RELEASE)
	92
	93	#else /* !defined (HAVE_ATOMIC_FUNCTIONS) */
	94	#ifdef HAVE_SYNC_FUNCTIONS
	95
	96	/* We have the sync functions but not the atomic functions. Define
	97	the atomic ones in terms of the sync ones. */
	98
	99	extern void backtrace_atomic_load_pointer (void );
	100	extern int backtrace_atomic_load_int (int *);
	101	extern void backtrace_atomic_store_pointer (void , void );
	102	extern void backtrace_atomic_store_size_t (size_t *, size_t);
	103	extern void backtrace_atomic_store_int (int *, int);
	104
	105	#else /* !defined (HAVE_SYNC_FUNCTIONS) */
	106
	107	/* We have neither the sync nor the atomic functions. These will
	108	never be called. */
	109
c96601d2	110	#define backtrace_atomic_load_pointer(p) (abort(), (void *) NULL)
49579c7e ILT	111	#define backtrace_atomic_load_int(p) (abort(), 0)
	112	#define backtrace_atomic_store_pointer(p, v) abort()
	113	#define backtrace_atomic_store_size_t(p, v) abort()
	114	#define backtrace_atomic_store_int(p, v) abort()
	115
	116	#endif /* !defined (HAVE_SYNC_FUNCTIONS) */
	117	#endif /* !defined (HAVE_ATOMIC_FUNCTIONS) */
eff02e4f ILT	118
	119	/* The type of the function that collects file/line information. This
	120	is like backtrace_pcinfo. */
	121
	122	typedef int (fileline) (struct backtrace_state state, uintptr_t pc,
	123	backtrace_full_callback callback,
	124	backtrace_error_callback error_callback, void *data);
	125
	126	/* The type of the function that collects symbol information. This is
	127	like backtrace_syminfo. */
	128
	129	typedef void (syminfo) (struct backtrace_state state, uintptr_t pc,
	130	backtrace_syminfo_callback callback,
	131	backtrace_error_callback error_callback, void *data);
	132
	133	/* What the backtrace state pointer points to. */
	134
	135	struct backtrace_state
	136	{
	137	/* The name of the executable. */
	138	const char *filename;
	139	/* Non-zero if threaded. */
	140	int threaded;
	141	/* The master lock for fileline_fn, fileline_data, syminfo_fn,
	142	syminfo_data, fileline_initialization_failed and everything the
	143	data pointers point to. */
	144	void *lock;
	145	/* The function that returns file/line information. */
	146	fileline fileline_fn;
	147	/* The data to pass to FILELINE_FN. */
	148	void *fileline_data;
	149	/* The function that returns symbol information. */
	150	syminfo syminfo_fn;
	151	/* The data to pass to SYMINFO_FN. */
	152	void *syminfo_data;
	153	/* Whether initializing the file/line information failed. */
	154	int fileline_initialization_failed;
	155	/* The lock for the freelist. */
	156	int lock_alloc;
	157	/* The freelist when using mmap. */
	158	struct backtrace_freelist_struct *freelist;
	159	};
	160
73f41491 ILT	161	/* Open a file for reading. Returns -1 on error. If DOES_NOT_EXIST
	162	is not NULL, *DOES_NOT_EXIST will be set to 0 normally and set to 1
	163	if the file does not exist. If the file does not exist and
	164	DOES_NOT_EXIST is not NULL, the function will return -1 and will
	165	not call ERROR_CALLBACK. On other errors, or if DOES_NOT_EXIST is
	166	NULL, the function will call ERROR_CALLBACK before returning. */
eff02e4f ILT	167	extern int backtrace_open (const char *filename,
eff02e4f ILT	168	backtrace_error_callback error_callback,
73f41491 ILT	169	void *data,
73f41491 ILT	170	int *does_not_exist);
eff02e4f ILT	171
	172	/* A view of the contents of a file. This supports mmap when
	173	available. A view will remain in memory even after backtrace_close
	174	is called on the file descriptor from which the view was
	175	obtained. */
	176
	177	struct backtrace_view
	178	{
	179	/* The data that the caller requested. */
	180	const void *data;
	181	/* The base of the view. */
	182	void *base;
	183	/* The total length of the view. */
	184	size_t len;
	185	};
	186
	187	/* Create a view of SIZE bytes from DESCRIPTOR at OFFSET. Store the
	188	result in VIEW. Returns 1 on success, 0 on error. /
	189	extern int backtrace_get_view (struct backtrace_state *state, int descriptor,
8b248c17	190	off_t offset, uint64_t size,
eff02e4f ILT	191	backtrace_error_callback error_callback,
	192	void data, struct backtrace_view view);
	193
	194	/* Release a view created by backtrace_get_view. */
	195	extern void backtrace_release_view (struct backtrace_state *state,
	196	struct backtrace_view *view,
	197	backtrace_error_callback error_callback,
	198	void *data);
	199
	200	/* Close a file opened by backtrace_open. Returns 1 on success, 0 on
	201	error. */
	202
	203	extern int backtrace_close (int descriptor,
	204	backtrace_error_callback error_callback,
	205	void *data);
	206
c5604b48 ILT	207	/* Sort without using memory. */
	208
	209	extern void backtrace_qsort (void *base, size_t count, size_t size,
	210	int (compar) (const void , const void *));
	211
c478516b ILT	212	/* Allocate memory. This is like malloc. If ERROR_CALLBACK is NULL,
c478516b ILT	213	this does not report an error, it just returns NULL. */
eff02e4f ILT	214
	215	extern void backtrace_alloc (struct backtrace_state state, size_t size,
	216	backtrace_error_callback error_callback,
	217	void *data) ATTRIBUTE_MALLOC;
	218
c478516b ILT	219	/* Free memory allocated by backtrace_alloc. If ERROR_CALLBACK is
c478516b ILT	220	NULL, this does not report an error. */
eff02e4f ILT	221
	222	extern void backtrace_free (struct backtrace_state state, void mem,
	223	size_t size,
	224	backtrace_error_callback error_callback,
	225	void *data);
	226
	227	/* A growable vector of some struct. This is used for more efficient
	228	allocation when we don't know the final size of some group of data
	229	that we want to represent as an array. */
	230
	231	struct backtrace_vector
	232	{
	233	/* The base of the vector. */
	234	void *base;
	235	/* The number of bytes in the vector. */
	236	size_t size;
	237	/* The number of bytes available at the current allocation. */
	238	size_t alc;
	239	};
	240
	241	/* Grow VEC by SIZE bytes. Return a pointer to the newly allocated
	242	bytes. Note that this may move the entire vector to a new memory
	243	location. Returns NULL on failure. */
	244
	245	extern void backtrace_vector_grow (struct backtrace_state state, size_t size,
	246	backtrace_error_callback error_callback,
	247	void *data,
	248	struct backtrace_vector *vec);
	249
	250	/* Finish the current allocation on VEC. Prepare to start a new
bfd74f22 ILT	251	allocation. The finished allocation will never be freed. Returns
	252	a pointer to the base of the finished entries, or NULL on
	253	failure. */
eff02e4f	254
bfd74f22 ILT	255	extern void* backtrace_vector_finish (struct backtrace_state *state,
	256	struct backtrace_vector *vec,
	257	backtrace_error_callback error_callback,
	258	void *data);
eff02e4f	259
bfd74f22 ILT	260	/* Release any extra space allocated for VEC. This may change
bfd74f22 ILT	261	VEC->base. Returns 1 on success, 0 on failure. */
eff02e4f ILT	262
	263	extern int backtrace_vector_release (struct backtrace_state *state,
	264	struct backtrace_vector *vec,
	265	backtrace_error_callback error_callback,
	266	void *data);
	267
518a3a21 TV	268	/* Free the space managed by VEC. This will reset VEC. */
	269
	270	static inline void
	271	backtrace_vector_free (struct backtrace_state *state,
	272	struct backtrace_vector *vec,
	273	backtrace_error_callback error_callback, void *data)
	274	{
	275	vec->alc += vec->size;
	276	vec->size = 0;
	277	backtrace_vector_release (state, vec, error_callback, data);
	278	}
	279
eff02e4f ILT	280	/* Read initial debug data from a descriptor, and set the
	281	fileline_data, syminfo_fn, and syminfo_data fields of STATE.
	282	Return the fileln_fn field in *FILELN_FN--this is done this way so
	283	that the synchronization code is only implemented once. This is
	284	called after the descriptor has first been opened. It will close
	285	the descriptor if it is no longer needed. Returns 1 on success, 0
	286	on error. There will be multiple implementations of this function,
	287	for different file formats. Each system will compile the
	288	appropriate one. */
	289
	290	extern int backtrace_initialize (struct backtrace_state *state,
9283471b	291	const char *filename,
eff02e4f ILT	292	int descriptor,
	293	backtrace_error_callback error_callback,
	294	void *data,
	295	fileline *fileline_fn);
	296
66ab5839 ILT	297	/* An enum for the DWARF sections we care about. */
	298
	299	enum dwarf_section
	300	{
	301	DEBUG_INFO,
	302	DEBUG_LINE,
	303	DEBUG_ABBREV,
	304	DEBUG_RANGES,
	305	DEBUG_STR,
c926fd82 ILT	306	DEBUG_ADDR,
	307	DEBUG_STR_OFFSETS,
	308	DEBUG_LINE_STR,
	309	DEBUG_RNGLISTS,
66ab5839 ILT	310
	311	DEBUG_MAX
	312	};
	313
	314	/* Data for the DWARF sections we care about. */
	315
	316	struct dwarf_sections
	317	{
	318	const unsigned char *data[DEBUG_MAX];
	319	size_t size[DEBUG_MAX];
	320	};
	321
	322	/* DWARF data read from a file, used for .gnu_debugaltlink. */
	323
e6f00c83 TV	324	struct dwarf_data;
e6f00c83 TV	325
e561a992 ILT	326	/* Add file/line information for a DWARF module. */
	327
	328	extern int backtrace_dwarf_add (struct backtrace_state *state,
	329	uintptr_t base_address,
66ab5839	330	const struct dwarf_sections *dwarf_sections,
e561a992	331	int is_bigendian,
9ad458d5	332	struct dwarf_data *fileline_altlink,
e561a992	333	backtrace_error_callback error_callback,
e6f00c83 TV	334	void data, fileline fileline_fn,
e6f00c83 TV	335	struct dwarf_data **fileline_entry);
eff02e4f	336
90c25456 ILT	337	/* A data structure to pass to backtrace_syminfo_to_full. */
	338
	339	struct backtrace_call_full
	340	{
	341	backtrace_full_callback full_callback;
	342	backtrace_error_callback full_error_callback;
	343	void *full_data;
	344	int ret;
	345	};
	346
	347	/* A backtrace_syminfo_callback that can call into a
	348	backtrace_full_callback, used when we have a symbol table but no
	349	debug info. */
	350
	351	extern void backtrace_syminfo_to_full_callback (void *data, uintptr_t pc,
	352	const char *symname,
	353	uintptr_t symval,
	354	uintptr_t symsize);
	355
	356	/* An error callback that corresponds to
	357	backtrace_syminfo_to_full_callback. */
	358
	359	extern void backtrace_syminfo_to_full_error_callback (void , const char ,
	360	int);
	361
8da872d9 ILT	362	/* A test-only hook for elf_uncompress_zdebug. */
	363
	364	extern int backtrace_uncompress_zdebug (struct backtrace_state *,
	365	const unsigned char *compressed,
	366	size_t compressed_size,
	367	backtrace_error_callback, void *data,
	368	unsigned char **uncompressed,
	369	size_t *uncompressed_size);
	370
05f40bc4 ILT	371	/* A test-only hook for elf_uncompress_lzma. */
	372
	373	extern int backtrace_uncompress_lzma (struct backtrace_state *,
	374	const unsigned char *compressed,
	375	size_t compressed_size,
	376	backtrace_error_callback, void *data,
	377	unsigned char **uncompressed,
	378	size_t *uncompressed_size);
	379
eff02e4f	380	#endif