gdbsupport/pathstuff.h

   1 /* Path manipulation routines for GDB and gdbserver.
   2
   3    Copyright (C) 1986-2024 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_PATHSTUFF_H
  21 #define COMMON_PATHSTUFF_H
  22
  23 #include "gdbsupport/byte-vector.h"
  24 #include "gdbsupport/array-view.h"
  25
  26 #include <sys/types.h>
  27 #include <sys/stat.h>
  28 #include <unistd.h>
  29 #include <array>
  30
  31 /* Path utilities.  */
  32
  33 /* Return the real path of FILENAME, expanding all the symbolic links.
  34
  35    Contrary to "gdb_abspath", this function does not use
  36    CURRENT_DIRECTORY for path expansion.  Instead, it relies on the
  37    current working directory (CWD) of GDB or gdbserver.  */
  38
  39 extern gdb::unique_xmalloc_ptr<char> gdb_realpath (const char *filename);
  40
  41 /* Return a copy of FILENAME, with its directory prefix canonicalized
  42    by gdb_realpath.  */
  43
  44 extern std::string gdb_realpath_keepfile (const char *filename);
  45
  46 /* Return PATH in absolute form, performing tilde-expansion if necessary.
  47    PATH cannot be NULL or the empty string.
  48    This does not resolve symlinks however, use gdb_realpath for that.
  49
  50    Contrary to "gdb_realpath", this function uses CURRENT_DIRECTORY
  51    for the path expansion.  This may lead to scenarios the current
  52    working directory (CWD) is different than CURRENT_DIRECTORY.
  53
  54    If CURRENT_DIRECTORY is NULL, this function returns a copy of
  55    PATH.  */
  56
  57 extern std::string gdb_abspath (const char *path);
  58
  59 /* Overload of gdb_abspath which takes std::string.  */
  60
  61 static inline std::string
  62 gdb_abspath (const std::string &path)
  63 {
  64   return gdb_abspath (path.c_str ());
  65 }
  66
  67 /* Overload of gdb_abspath which takes gdb::unique_xmalloc_ptr<char>.  */
  68
  69 static inline std::string
  70 gdb_abspath (const gdb::unique_xmalloc_ptr<char> &path)
  71 {
  72   return gdb_abspath (path.get ());
  73 }
  74
  75 /* If the path in CHILD is a child of the path in PARENT, return a
  76    pointer to the first component in the CHILD's pathname below the
  77    PARENT.  Otherwise, return NULL.  */
  78
  79 extern const char *child_path (const char *parent, const char *child);
  80
  81 /* Join elements in PATHS into a single path.
  82
  83    The first element can be absolute or relative.  Only a single directory
  84    separator will be placed between elements of PATHS, if one element ends
  85    with a directory separator, or an element starts with a directory
  86    separator, then these will be collapsed into a single separator.  */
  87
  88 extern std::string path_join (gdb::array_view<const char *> paths);
  89
  90 /* Same as the above, but accept paths as distinct parameters.  */
  91
  92 template<typename ...Args>
  93 std::string
  94 path_join (Args... paths)
  95 {
  96   /* It doesn't make sense to join less than two paths.  */
  97   static_assert (sizeof... (Args) >= 2);
  98
  99   std::array<const char *, sizeof... (Args)> path_array
 100     { paths... };
 101
 102   return path_join (gdb::array_view<const char *> (path_array));
 103 }
 104
 105 /* Return whether PATH contains a directory separator character.  */
 106
 107 extern bool contains_dir_separator (const char *path);
 108
 109 /* Get the usual user cache directory for the current platform.
 110
 111    On Linux, it follows the XDG Base Directory specification: use
 112    $XDG_CACHE_HOME/gdb if the XDG_CACHE_HOME environment variable is
 113    defined, otherwise $HOME/.cache.
 114
 115    On macOS, it follows the local convention and uses
 116    ~/Library/Caches/gdb.
 117
 118   The return value is absolute and tilde-expanded.  Return an empty
 119   string if neither XDG_CACHE_HOME (on Linux) or HOME are defined.  */
 120
 121 extern std::string get_standard_cache_dir ();
 122
 123 /* Get the usual temporary directory for the current platform.
 124
 125    On Windows, this is the TMP or TEMP environment variable.
 126
 127    On the rest, this is the TMPDIR environment variable, if defined, else /tmp.
 128
 129    Throw an exception on error.  */
 130
 131 extern std::string get_standard_temp_dir ();
 132
 133 /* Get the usual user config directory for the current platform.
 134
 135    On Linux, it follows the XDG Base Directory specification: use
 136    $XDG_CONFIG_HOME/gdb if the XDG_CONFIG_HOME environment variable is
 137    defined, otherwise $HOME/.config.
 138
 139    On macOS, it follows the local convention and uses
 140    ~/Library/Preferences/gdb.
 141
 142   The return value is absolute and tilde-expanded.  Return an empty
 143   string if neither XDG_CONFIG_HOME (on Linux) or HOME are defined.  */
 144
 145 extern std::string get_standard_config_dir ();
 146
 147 /* Look for FILENAME in the standard configuration directory as returned by
 148    GET_STANDARD_CONFIG_DIR and return the path to the file.  No check is
 149    performed that the file actually exists or not.
 150
 151    If FILENAME begins with a '.' then the path returned will remove the
 152    leading '.' character, for example passing '.gdbinit' could return the
 153    path '/home/username/.config/gdb/gdbinit'.  */
 154
 155 extern std::string get_standard_config_filename (const char *filename);
 156
 157 /* Look for a file called NAME in either the standard config directory or
 158    in the users home directory.  If a suitable file is found then *BUF will
 159    be filled with the contents of a call to 'stat' on the found file,
 160    otherwise *BUF is undefined after this call.
 161
 162    If NAME starts with a '.' character then, when looking in the standard
 163    config directory the file searched for has the '.' removed.  For
 164    example, if NAME is '.gdbinit' then on a Linux target GDB might look for
 165    '~/.config/gdb/gdbinit' and then '~/.gdbinit'.  */
 166
 167 extern std::string find_gdb_home_config_file (const char *name,
 168                                               struct stat *buf);
 169
 170 /* Return the file name of the user's shell.  Normally this comes from
 171    the SHELL environment variable.  */
 172
 173 extern const char *get_shell ();
 174
 175 /* Make a filename suitable to pass to mkstemp based on F (e.g.
 176    /tmp/foo -> /tmp/foo-XXXXXX).  */
 177
 178 extern gdb::char_vector make_temp_filename (const std::string &f);
 179
 180 /* String containing the current directory (what getwd would return).  */
 181 extern char *current_directory;
 182
 183 #endif /* COMMON_PATHSTUFF_H */