gdbsupport/common-utils.h

   1 /* Shared general utility routines for GDB, the GNU debugger.
   2
   3    Copyright (C) 1986-2022 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 #include "gdbsupport/byte-vector.h"
  26 #include "gdbsupport/gdb_unique_ptr.h"
  27 #include "poison.h"
  28 #include "gdb_string_view.h"
  29
  30 /* xmalloc(), xrealloc() and xcalloc() have already been declared in
  31    "libiberty.h". */
  32
  33 /* Like xmalloc, but zero the memory.  */
  34 void *xzalloc (size_t);
  35
  36 /* Like asprintf and vasprintf, but return the string, throw an error
  37    if no memory.  */
  38 gdb::unique_xmalloc_ptr<char> xstrprintf (const char *format, ...)
  39      ATTRIBUTE_PRINTF (1, 2);
  40 gdb::unique_xmalloc_ptr<char> xstrvprintf (const char *format, va_list ap)
  41      ATTRIBUTE_PRINTF (1, 0);
  42
  43 /* Like snprintf, but throw an error if the output buffer is too small.  */
  44 int xsnprintf (char *str, size_t size, const char *format, ...)
  45      ATTRIBUTE_PRINTF (3, 4);
  46
  47 /* Returns a std::string built from a printf-style format string.  */
  48 std::string string_printf (const char* fmt, ...)
  49   ATTRIBUTE_PRINTF (1, 2);
  50
  51 /* Like string_printf, but takes a va_list.  */
  52 std::string string_vprintf (const char* fmt, va_list args)
  53   ATTRIBUTE_PRINTF (1, 0);
  54
  55 /* Like string_printf, but appends to DEST instead of returning a new
  56    std::string.  */
  57 std::string &string_appendf (std::string &dest, const char* fmt, ...)
  58   ATTRIBUTE_PRINTF (2, 3);
  59
  60 /* Like string_appendf, but takes a va_list.  */
  61 std::string &string_vappendf (std::string &dest, const char* fmt, va_list args)
  62   ATTRIBUTE_PRINTF (2, 0);
  63
  64 /* Make a copy of the string at PTR with LEN characters
  65    (and add a null character at the end in the copy).
  66    Uses malloc to get the space.  Returns the address of the copy.  */
  67
  68 char *savestring (const char *ptr, size_t len);
  69
  70 /* Extract the next word from ARG.  The next word is defined as either,
  71    everything up to the next space, or, if the next word starts with either
  72    a single or double quote, then everything up to the closing quote.  The
  73    enclosing quotes are not returned in the result string.  The pointer in
  74    ARG is updated to point to the first character after the end of the
  75    word, or, for quoted words, the first character after the closing
  76    quote.  */
  77
  78 std::string extract_string_maybe_quoted (const char **arg);
  79
  80 /* The strerror() function can return NULL for errno values that are
  81    out of range.  Provide a "safe" version that always returns a
  82    printable string.  This version is also thread-safe.  */
  83
  84 extern const char *safe_strerror (int);
  85
  86 /* Version of startswith that takes string_view arguments.  Return
  87    true if the start of STRING matches PATTERN, false otherwise.  */
  88
  89 static inline bool
  90 startswith (gdb::string_view string, gdb::string_view pattern)
  91 {
  92   return (string.length () >= pattern.length ()
  93           && strncmp (string.data (), pattern.data (), pattern.length ()) == 0);
  94 }
  95
  96 ULONGEST strtoulst (const char *num, const char **trailer, int base);
  97
  98 /* Skip leading whitespace characters in INP, returning an updated
  99    pointer.  If INP is NULL, return NULL.  */
 100
 101 extern char *skip_spaces (char *inp);
 102
 103 /* A const-correct version of the above.  */
 104
 105 extern const char *skip_spaces (const char *inp);
 106
 107 /* Skip leading non-whitespace characters in INP, returning an updated
 108    pointer.  If INP is NULL, return NULL.  */
 109
 110 extern char *skip_to_space (char *inp);
 111
 112 /* A const-correct version of the above.  */
 113
 114 extern const char *skip_to_space (const char *inp);
 115
 116 /* Assumes that V is an argv for a program, and iterates through
 117    freeing all the elements.  */
 118 extern void free_vector_argv (std::vector<char *> &v);
 119
 120 /* Return true if VALUE is in [LOW, HIGH].  */
 121
 122 template <typename T>
 123 static bool
 124 in_inclusive_range (T value, T low, T high)
 125 {
 126   return value >= low && value <= high;
 127 }
 128
 129 /* Ensure that V is aligned to an N byte boundary (N's assumed to be a
 130    power of 2).  Round up/down when necessary.  Examples of correct
 131    use include:
 132
 133     addr = align_up (addr, 8); -- VALUE needs 8 byte alignment
 134     write_memory (addr, value, len);
 135     addr += len;
 136
 137    and:
 138
 139     sp = align_down (sp - len, 16); -- Keep SP 16 byte aligned
 140     write_memory (sp, value, len);
 141
 142    Note that uses such as:
 143
 144     write_memory (addr, value, len);
 145     addr += align_up (len, 8);
 146
 147    and:
 148
 149     sp -= align_up (len, 8);
 150     write_memory (sp, value, len);
 151
 152    are typically not correct as they don't ensure that the address (SP
 153    or ADDR) is correctly aligned (relying on previous alignment to
 154    keep things right).  This is also why the methods are called
 155    "align_..." instead of "round_..." as the latter reads better with
 156    this incorrect coding style.  */
 157
 158 extern ULONGEST align_up (ULONGEST v, int n);
 159 extern ULONGEST align_down (ULONGEST v, int n);
 160
 161 /* Convert hex digit A to a number, or throw an exception.  */
 162 extern int fromhex (int a);
 163
 164 /* HEX is a string of characters representing hexadecimal digits.
 165    Convert pairs of hex digits to bytes and store sequentially into
 166    BIN.  COUNT is the maximum number of characters to convert.  This
 167    will convert fewer characters if the number of hex characters
 168    actually seen is odd, or if HEX terminates before COUNT characters.
 169    Returns the number of characters actually converted.  */
 170 extern int hex2bin (const char *hex, gdb_byte *bin, int count);
 171
 172 /* Like the above, but return a gdb::byte_vector.  */
 173 gdb::byte_vector hex2bin (const char *hex);
 174
 175 #endif /* COMMON_COMMON_UTILS_H */