gdbsupport/pathstuff.h

   1 /* Path manipulation routines for GDB and gdbserver.
   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_PATHSTUFF_H
  21 #define COMMON_PATHSTUFF_H
  22
  23 #include "gdbsupport/byte-vector.h"
  24
  25 #include <sys/types.h>
  26 #include <sys/stat.h>
  27 #include <unistd.h>
  28
  29 /* Path utilities.  */
  30
  31 /* Return the real path of FILENAME, expanding all the symbolic links.
  32
  33    Contrary to "gdb_abspath", this function does not use
  34    CURRENT_DIRECTORY for path expansion.  Instead, it relies on the
  35    current working directory (CWD) of GDB or gdbserver.  */
  36
  37 extern gdb::unique_xmalloc_ptr<char> gdb_realpath (const char *filename);
  38
  39 /* Return a copy of FILENAME, with its directory prefix canonicalized
  40    by gdb_realpath.  */
  41
  42 extern gdb::unique_xmalloc_ptr<char>
  43   gdb_realpath_keepfile (const char *filename);
  44
  45 /* Return PATH in absolute form, performing tilde-expansion if necessary.
  46    PATH cannot be NULL or the empty string.
  47    This does not resolve symlinks however, use gdb_realpath for that.
  48
  49    Contrary to "gdb_realpath", this function uses CURRENT_DIRECTORY
  50    for the path expansion.  This may lead to scenarios the current
  51    working directory (CWD) is different than CURRENT_DIRECTORY.
  52
  53    If CURRENT_DIRECTORY is NULL, this function returns a copy of
  54    PATH.  */
  55
  56 extern gdb::unique_xmalloc_ptr<char> gdb_abspath (const char *path);
  57
  58 /* If the path in CHILD is a child of the path in PARENT, return a
  59    pointer to the first component in the CHILD's pathname below the
  60    PARENT.  Otherwise, return NULL.  */
  61
  62 extern const char *child_path (const char *parent, const char *child);
  63
  64 /* Return whether PATH contains a directory separator character.  */
  65
  66 extern bool contains_dir_separator (const char *path);
  67
  68 /* Get the usual user cache directory for the current platform.
  69
  70    On Linux, it follows the XDG Base Directory specification: use
  71    $XDG_CACHE_HOME/gdb if the XDG_CACHE_HOME environment variable is
  72    defined, otherwise $HOME/.cache.
  73
  74    On macOS, it follows the local convention and uses
  75    ~/Library/Caches/gdb.
  76
  77   The return value is absolute and tilde-expanded.  Return an empty
  78   string if neither XDG_CACHE_HOME (on Linux) or HOME are defined.  */
  79
  80 extern std::string get_standard_cache_dir ();
  81
  82 /* Get the usual temporary directory for the current platform.
  83
  84    On Windows, this is the TMP or TEMP environment variable.
  85
  86    On the rest, this is the TMPDIR environment variable, if defined, else /tmp.
  87
  88    Throw an exception on error.  */
  89
  90 extern std::string get_standard_temp_dir ();
  91
  92 /* Get the usual user config directory for the current platform.
  93
  94    On Linux, it follows the XDG Base Directory specification: use
  95    $XDG_CONFIG_HOME/gdb if the XDG_CONFIG_HOME environment variable is
  96    defined, otherwise $HOME/.config.
  97
  98    On macOS, it follows the local convention and uses
  99    ~/Library/Preferences/gdb.
 100
 101   The return value is absolute and tilde-expanded.  Return an empty
 102   string if neither XDG_CONFIG_HOME (on Linux) or HOME are defined.  */
 103
 104 extern std::string get_standard_config_dir ();
 105
 106 /* Look for FILENAME in the standard configuration directory as returned by
 107    GET_STANDARD_CONFIG_DIR and return the path to the file.  No check is
 108    performed that the file actually exists or not.
 109
 110    If FILENAME begins with a '.' then the path returned will remove the
 111    leading '.' character, for example passing '.gdbinit' could return the
 112    path '/home/username/.config/gdb/gdbinit'.  */
 113
 114 extern std::string get_standard_config_filename (const char *filename);
 115
 116 /* Look for a file called NAME in either the standard config directory or
 117    in the users home directory.  If a suitable file is found then *BUF will
 118    be filled with the contents of a call to 'stat' on the found file,
 119    otherwise *BUF is undefined after this call.
 120
 121    If NAME starts with a '.' character then, when looking in the standard
 122    config directory the file searched for has the '.' removed.  For
 123    example, if NAME is '.gdbinit' then on a Linux target GDB might look for
 124    '~/.config/gdb/gdbinit' and then '~/.gdbinit'.  */
 125
 126 extern std::string find_gdb_home_config_file (const char *name,
 127                                               struct stat *buf);
 128
 129 /* Return the file name of the user's shell.  Normally this comes from
 130    the SHELL environment variable.  */
 131
 132 extern const char *get_shell ();
 133
 134 /* Make a filename suitable to pass to mkstemp based on F (e.g.
 135    /tmp/foo -> /tmp/foo-XXXXXX).  */
 136
 137 extern gdb::char_vector make_temp_filename (const std::string &f);
 138
 139 #endif /* COMMON_PATHSTUFF_H */