[deliverable/binutils-gdb.git] / gdb / gdbsupport / common-utils.h

/* Shared general utility routines for GDB, the GNU debugger.

   Copyright (C) 1986-2019 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 COMMON_COMMON_UTILS_H
#define COMMON_COMMON_UTILS_H

#include <string>
#include <vector>

#include "poison.h"

/* If possible, define FUNCTION_NAME, a macro containing the name of
   the function being defined.  Since this macro may not always be
   defined, all uses must be protected by appropriate macro definition
   checks (Eg: "#ifdef FUNCTION_NAME").

   Version 2.4 and later of GCC define a magical variable `__PRETTY_FUNCTION__'
   which contains the name of the function currently being defined.
   This is broken in G++ before version 2.6.
   C9x has a similar variable called __func__, but prefer the GCC one since
   it demangles C++ function names.  */
#if (GCC_VERSION >= 2004)
#define FUNCTION_NAME		__PRETTY_FUNCTION__
#else
#if defined __STDC_VERSION__ && __STDC_VERSION__ >= 199901L
#define FUNCTION_NAME		__func__  /* ARI: func */
#endif
#endif

/* xmalloc(), xrealloc() and xcalloc() have already been declared in
   "libiberty.h". */

/* Like xmalloc, but zero the memory.  */
void *xzalloc (size_t);

template <typename T>
static void
xfree (T *ptr)
{
  static_assert (IsFreeable<T>::value, "Trying to use xfree with a non-POD \
data type.  Use operator delete instead.");

  if (ptr != NULL)
    free (ptr);		/* ARI: free */
}


/* Like asprintf and vasprintf, but return the string, throw an error
   if no memory.  */
char *xstrprintf (const char *format, ...) ATTRIBUTE_PRINTF (1, 2);
char *xstrvprintf (const char *format, va_list ap)
     ATTRIBUTE_PRINTF (1, 0);

/* Like snprintf, but throw an error if the output buffer is too small.  */
int xsnprintf (char *str, size_t size, const char *format, ...)
     ATTRIBUTE_PRINTF (3, 4);

/* Returns a std::string built from a printf-style format string.  */
std::string string_printf (const char* fmt, ...)
  ATTRIBUTE_PRINTF (1, 2);

/* Like string_printf, but takes a va_list.  */
std::string string_vprintf (const char* fmt, va_list args)
  ATTRIBUTE_PRINTF (1, 0);

/* Like string_printf, but appends to DEST instead of returning a new
   std::string.  */
void string_appendf (std::string &dest, const char* fmt, ...)
  ATTRIBUTE_PRINTF (2, 3);

/* Like string_appendf, but takes a va_list.  */
void string_vappendf (std::string &dest, const char* fmt, va_list args)
  ATTRIBUTE_PRINTF (2, 0);

/* Make a copy of the string at PTR with LEN characters
   (and add a null character at the end in the copy).
   Uses malloc to get the space.  Returns the address of the copy.  */

char *savestring (const char *ptr, size_t len);

/* Extract the next word from ARG.  The next word is defined as either,
   everything up to the next space, or, if the next word starts with either
   a single or double quote, then everything up to the closing quote.  The
   enclosing quotes are not returned in the result string.  The pointer in
   ARG is updated to point to the first character after the end of the
   word, or, for quoted words, the first character after the closing
   quote.  */

std::string extract_string_maybe_quoted (const char **arg);

/* The strerror() function can return NULL for errno values that are
   out of range.  Provide a "safe" version that always returns a
   printable string.  */

extern char *safe_strerror (int);

/* Return true if the start of STRING matches PATTERN, false otherwise.  */

static inline bool
startswith (const char *string, const char *pattern)
{
  return strncmp (string, pattern, strlen (pattern)) == 0;
}

ULONGEST strtoulst (const char *num, const char **trailer, int base);

/* Skip leading whitespace characters in INP, returning an updated
   pointer.  If INP is NULL, return NULL.  */

extern char *skip_spaces (char *inp);

/* A const-correct version of the above.  */

extern const char *skip_spaces (const char *inp);

/* Skip leading non-whitespace characters in INP, returning an updated
   pointer.  If INP is NULL, return NULL.  */

extern char *skip_to_space (char *inp);

/* A const-correct version of the above.  */

extern const char *skip_to_space (const char *inp);

/* Assumes that V is an argv for a program, and iterates through
   freeing all the elements.  */
extern void free_vector_argv (std::vector<char *> &v);

/* Given a vector of arguments ARGV, return a string equivalent to
   joining all the arguments with a whitespace separating them.  */
extern std::string stringify_argv (const std::vector<char *> &argv);

/* Return true if VALUE is in [LOW, HIGH].  */

template <typename T>
static bool
in_inclusive_range (T value, T low, T high)
{
  return value >= low && value <= high;
}

/* Ensure that V is aligned to an N byte boundary (B's assumed to be a
   power of 2).  Round up/down when necessary.  Examples of correct
   use include:

    addr = align_up (addr, 8); -- VALUE needs 8 byte alignment
    write_memory (addr, value, len);
    addr += len;

   and:

    sp = align_down (sp - len, 16); -- Keep SP 16 byte aligned
    write_memory (sp, value, len);

   Note that uses such as:

    write_memory (addr, value, len);
    addr += align_up (len, 8);

   and:

    sp -= align_up (len, 8);
    write_memory (sp, value, len);

   are typically not correct as they don't ensure that the address (SP
   or ADDR) is correctly aligned (relying on previous alignment to
   keep things right).  This is also why the methods are called
   "align_..." instead of "round_..." as the latter reads better with
   this incorrect coding style.  */

extern ULONGEST align_up (ULONGEST v, int n);
extern ULONGEST align_down (ULONGEST v, int n);

#endif /* COMMON_COMMON_UTILS_H */
Commit	Line	Data
	1	/* Shared general utility routines for GDB, the GNU debugger.
	2
	3	Copyright (C) 1986-2019 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 COMMON_COMMON_UTILS_H
	21	#define COMMON_COMMON_UTILS_H
	22
	23	#include <string>
	24	#include <vector>
	25
	26	#include "poison.h"
	27
	28	/* If possible, define FUNCTION_NAME, a macro containing the name of
	29	the function being defined. Since this macro may not always be
	30	defined, all uses must be protected by appropriate macro definition
	31	checks (Eg: "#ifdef FUNCTION_NAME").
	32
	33	Version 2.4 and later of GCC define a magical variable `__PRETTY_FUNCTION__'
	34	which contains the name of the function currently being defined.
	35	This is broken in G++ before version 2.6.
	36	C9x has a similar variable called __func__, but prefer the GCC one since
	37	it demangles C++ function names. */
	38	#if (GCC_VERSION >= 2004)
	39	#define FUNCTION_NAME __PRETTY_FUNCTION__
	40	#else
	41	#if defined __STDC_VERSION__ && __STDC_VERSION__ >= 199901L
	42	#define FUNCTION_NAME __func__ /* ARI: func */
	43	#endif
	44	#endif
	45
	46	/* xmalloc(), xrealloc() and xcalloc() have already been declared in
	47	"libiberty.h". */
	48
	49	/* Like xmalloc, but zero the memory. */
	50	void *xzalloc (size_t);
	51
	52	template <typename T>
	53	static void
	54	xfree (T *ptr)
	55	{
	56	static_assert (IsFreeable<T>::value, "Trying to use xfree with a non-POD \
	57	data type. Use operator delete instead.");
	58
	59	if (ptr != NULL)
	60	free (ptr); /* ARI: free */
	61	}
	62
	63
	64	/* Like asprintf and vasprintf, but return the string, throw an error
	65	if no memory. */
	66	char xstrprintf (const char format, ...) ATTRIBUTE_PRINTF (1, 2);
	67	char xstrvprintf (const char format, va_list ap)
	68	ATTRIBUTE_PRINTF (1, 0);
	69
	70	/* Like snprintf, but throw an error if the output buffer is too small. */
	71	int xsnprintf (char str, size_t size, const char format, ...)
	72	ATTRIBUTE_PRINTF (3, 4);
	73
	74	/* Returns a std::string built from a printf-style format string. */
	75	std::string string_printf (const char* fmt, ...)
	76	ATTRIBUTE_PRINTF (1, 2);
	77
	78	/* Like string_printf, but takes a va_list. */
	79	std::string string_vprintf (const char* fmt, va_list args)
	80	ATTRIBUTE_PRINTF (1, 0);
	81
	82	/* Like string_printf, but appends to DEST instead of returning a new
	83	std::string. */
	84	void string_appendf (std::string &dest, const char* fmt, ...)
	85	ATTRIBUTE_PRINTF (2, 3);
	86
	87	/* Like string_appendf, but takes a va_list. */
	88	void string_vappendf (std::string &dest, const char* fmt, va_list args)
	89	ATTRIBUTE_PRINTF (2, 0);
	90
	91	/* Make a copy of the string at PTR with LEN characters
	92	(and add a null character at the end in the copy).
	93	Uses malloc to get the space. Returns the address of the copy. */
	94
	95	char savestring (const char ptr, size_t len);
	96
	97	/* Extract the next word from ARG. The next word is defined as either,
	98	everything up to the next space, or, if the next word starts with either
	99	a single or double quote, then everything up to the closing quote. The
	100	enclosing quotes are not returned in the result string. The pointer in
	101	ARG is updated to point to the first character after the end of the
	102	word, or, for quoted words, the first character after the closing
	103	quote. */
	104
	105	std::string extract_string_maybe_quoted (const char **arg);
	106
	107	/* The strerror() function can return NULL for errno values that are
	108	out of range. Provide a "safe" version that always returns a
	109	printable string. */
	110
	111	extern char *safe_strerror (int);
	112
	113	/* Return true if the start of STRING matches PATTERN, false otherwise. */
	114
	115	static inline bool
	116	startswith (const char string, const char pattern)
	117	{
	118	return strncmp (string, pattern, strlen (pattern)) == 0;
	119	}
	120
	121	ULONGEST strtoulst (const char num, const char *trailer, int base);
	122
	123	/* Skip leading whitespace characters in INP, returning an updated
	124	pointer. If INP is NULL, return NULL. */
	125
	126	extern char skip_spaces (char inp);
	127
	128	/* A const-correct version of the above. */
	129
	130	extern const char skip_spaces (const char inp);
	131
	132	/* Skip leading non-whitespace characters in INP, returning an updated
	133	pointer. If INP is NULL, return NULL. */
	134
	135	extern char skip_to_space (char inp);
	136
	137	/* A const-correct version of the above. */
	138
	139	extern const char skip_to_space (const char inp);
	140
	141	/* Assumes that V is an argv for a program, and iterates through
	142	freeing all the elements. */
	143	extern void free_vector_argv (std::vector<char *> &v);
	144
	145	/* Given a vector of arguments ARGV, return a string equivalent to
	146	joining all the arguments with a whitespace separating them. */
	147	extern std::string stringify_argv (const std::vector<char *> &argv);
	148
	149	/* Return true if VALUE is in [LOW, HIGH]. */
	150
	151	template <typename T>
	152	static bool
	153	in_inclusive_range (T value, T low, T high)
	154	{
	155	return value >= low && value <= high;
	156	}
	157
	158	/* Ensure that V is aligned to an N byte boundary (B's assumed to be a
	159	power of 2). Round up/down when necessary. Examples of correct
	160	use include:
	161
	162	addr = align_up (addr, 8); -- VALUE needs 8 byte alignment
	163	write_memory (addr, value, len);
	164	addr += len;
	165
	166	and:
	167
	168	sp = align_down (sp - len, 16); -- Keep SP 16 byte aligned
	169	write_memory (sp, value, len);
	170
	171	Note that uses such as:
	172
	173	write_memory (addr, value, len);
	174	addr += align_up (len, 8);
	175
	176	and:
	177
	178	sp -= align_up (len, 8);
	179	write_memory (sp, value, len);
	180
	181	are typically not correct as they don't ensure that the address (SP
	182	or ADDR) is correctly aligned (relying on previous alignment to
	183	keep things right). This is also why the methods are called
	184	"align_..." instead of "round_..." as the latter reads better with
	185	this incorrect coding style. */
	186
	187	extern ULONGEST align_up (ULONGEST v, int n);
	188	extern ULONGEST align_down (ULONGEST v, int n);
	189
	190	#endif /* COMMON_COMMON_UTILS_H */