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 /* If the path in CHILD is a child of the path in PARENT, return a
  60    pointer to the first component in the CHILD's pathname below the
  61    PARENT.  Otherwise, return NULL.  */
  62
  63 extern const char *child_path (const char *parent, const char *child);
  64
  65 /* Join elements in PATHS into a single path.
  66
  67    The first element can be absolute or relative.  All the others must be
  68    relative.  */
  69
  70 extern std::string path_join (gdb::array_view<const char *> paths);
  71
  72 /* Same as the above, but accept paths as distinct parameters.  */
  73
  74 template<typename ...Args>
  75 std::string
  76 path_join (Args... paths)
  77 {
  78   /* It doesn't make sense to join less than two paths.  */
  79   static_assert (sizeof... (Args) >= 2);
  80
  81   std::array<const char *, sizeof... (Args)> path_array
  82     { paths... };
  83
  84   return path_join (gdb::array_view<const char *> (path_array));
  85 }
  86
  87 /* Return whether PATH contains a directory separator character.  */
  88
  89 extern bool contains_dir_separator (const char *path);
  90
  91 /* Get the usual user cache directory for the current platform.
  92
  93    On Linux, it follows the XDG Base Directory specification: use
  94    $XDG_CACHE_HOME/gdb if the XDG_CACHE_HOME environment variable is
  95    defined, otherwise $HOME/.cache.
  96
  97    On macOS, it follows the local convention and uses
  98    ~/Library/Caches/gdb.
  99
 100   The return value is absolute and tilde-expanded.  Return an empty
 101   string if neither XDG_CACHE_HOME (on Linux) or HOME are defined.  */
 102
 103 extern std::string get_standard_cache_dir ();
 104
 105 /* Get the usual temporary directory for the current platform.
 106
 107    On Windows, this is the TMP or TEMP environment variable.
 108
 109    On the rest, this is the TMPDIR environment variable, if defined, else /tmp.
 110
 111    Throw an exception on error.  */
 112
 113 extern std::string get_standard_temp_dir ();
 114
 115 /* Get the usual user config directory for the current platform.
 116
 117    On Linux, it follows the XDG Base Directory specification: use
 118    $XDG_CONFIG_HOME/gdb if the XDG_CONFIG_HOME environment variable is
 119    defined, otherwise $HOME/.config.
 120
 121    On macOS, it follows the local convention and uses
 122    ~/Library/Preferences/gdb.
 123
 124   The return value is absolute and tilde-expanded.  Return an empty
 125   string if neither XDG_CONFIG_HOME (on Linux) or HOME are defined.  */
 126
 127 extern std::string get_standard_config_dir ();
 128
 129 /* Look for FILENAME in the standard configuration directory as returned by
 130    GET_STANDARD_CONFIG_DIR and return the path to the file.  No check is
 131    performed that the file actually exists or not.
 132
 133    If FILENAME begins with a '.' then the path returned will remove the
 134    leading '.' character, for example passing '.gdbinit' could return the
 135    path '/home/username/.config/gdb/gdbinit'.  */
 136
 137 extern std::string get_standard_config_filename (const char *filename);
 138
 139 /* Look for a file called NAME in either the standard config directory or
 140    in the users home directory.  If a suitable file is found then *BUF will
 141    be filled with the contents of a call to 'stat' on the found file,
 142    otherwise *BUF is undefined after this call.
 143
 144    If NAME starts with a '.' character then, when looking in the standard
 145    config directory the file searched for has the '.' removed.  For
 146    example, if NAME is '.gdbinit' then on a Linux target GDB might look for
 147    '~/.config/gdb/gdbinit' and then '~/.gdbinit'.  */
 148
 149 extern std::string find_gdb_home_config_file (const char *name,
 150                                               struct stat *buf);
 151
 152 /* Return the file name of the user's shell.  Normally this comes from
 153    the SHELL environment variable.  */
 154
 155 extern const char *get_shell ();
 156
 157 /* Make a filename suitable to pass to mkstemp based on F (e.g.
 158    /tmp/foo -> /tmp/foo-XXXXXX).  */
 159
 160 extern gdb::char_vector make_temp_filename (const std::string &f);
 161
 162 /* String containing the current directory (what getwd would return).  */
 163 extern char *current_directory;
 164
 165 #endif /* COMMON_PATHSTUFF_H */