1// Copyright (c) 2017-present The Bitcoin Core developers
2// Distributed under the MIT software license, see the accompanying
3// file COPYING or http://www.opensource.org/licenses/mit-license.php.
4
5#ifndef BITCOIN_UTIL_FS_H
6#define BITCOIN_UTIL_FS_H
7
8#include <tinyformat.h>
9
10#include <cstdio>
11// The `util/fs.h` header is designed to be a drop-in replacement for `filesystem`.
12#include <filesystem> // IWYU pragma: export
13#include <functional>
14#include <iomanip>
15#include <ios>
16#include <string>
17#include <string_view>
18#include <type_traits>
19#include <utility>
20
21/** Filesystem operations and types */
22namespace fs {
23
24using namespace std::filesystem;
25
26/**
27 * Path class wrapper to block calls to the fs::path(std::string) implicit
28 * constructor and the fs::path::string() method, which have unsafe and
29 * unpredictable behavior on Windows (see implementation note in
30 * \ref PathToString for details)
31 */
32class path : public std::filesystem::path
33{
34public:
35    using std::filesystem::path::path;
36
37    // Convenience method for accessing standard path type without needing a cast.
38    std::filesystem::path& std_path() { return *this; }
39    const std::filesystem::path& std_path() const { return *this; }
40
41    // Allow path objects arguments for compatibility.
42    path(std::filesystem::path path) : std::filesystem::path::path(std::move(path)) {}
43    path& operator=(std::filesystem::path path) { std::filesystem::path::operator=(std::move(path)); return *this; }
44    path& operator/=(const std::filesystem::path& path) { std::filesystem::path::operator/=(path); return *this; }
45
46    // Allow literal string arguments, which are safe as long as the literals are ASCII.
47    path(const char* c) : std::filesystem::path(c) {}
48    path& operator=(const char* c) { std::filesystem::path::operator=(c); return *this; }
49    path& operator/=(const char* c) { std::filesystem::path::operator/=(c); return *this; }
50    path& append(const char* c) { std::filesystem::path::append(c); return *this; }
51
52    // Disallow std::string arguments to avoid locale-dependent decoding on windows.
53    path(std::string) = delete;
54    path& operator=(std::string) = delete;
55    path& operator/=(std::string) = delete;
56    path& append(std::string) = delete;
57
58    // Disallow std::string conversion method to avoid locale-dependent encoding on windows.
59    std::string string() const = delete;
60
61    // Disallow implicit string conversion to ensure code is portable.
62    // `string_type` may be `string` or `wstring` depending on the platform, so
63    // using this conversion could result in code that compiles on unix but
64    // fails to compile on windows, or vice versa.
65    operator string_type() const = delete;
66
67    /**
68     * Return a UTF-8 representation of the path as a std::string, for
69     * compatibility with code using std::string. For code using the newer
70     * std::u8string type, it is more efficient to call the inherited
71     * std::filesystem::path::u8string method instead.
72     */
73    std::string utf8string() const
74    {
75        const std::u8string& utf8_str{std::filesystem::path::u8string()};
76        return std::string{utf8_str.begin(), utf8_str.end()};
77    }
78};
79
80static inline path u8path(std::string_view utf8_str)
81{
82    return std::filesystem::path(std::u8string{utf8_str.begin(), utf8_str.end()});
83}
84
85// Disallow implicit std::string conversion for absolute to avoid
86// locale-dependent encoding on windows.
87static inline path absolute(const path& p)
88{
89    return std::filesystem::absolute(p);
90}
91
92// Disallow implicit std::string conversion for exists to avoid
93// locale-dependent encoding on windows.
94static inline bool exists(const path& p)
95{
96    return std::filesystem::exists(p);
97}
98static inline bool exists(const std::filesystem::file_status& s)
99{
100    return std::filesystem::exists(s);
101}
102
103// Allow explicit quoted stream I/O.
104static inline auto quoted(const std::string& s)
105{
106    return std::quoted(s, '"', '&');
107}
108
109// Allow safe path append operations.
110static inline path operator/(path p1, const path& p2)
111{
112    p1 /= p2;
113    return p1;
114}
115static inline path operator/(path p1, const char* p2)
116{
117    p1 /= p2;
118    return p1;
119}
120static inline path operator+(path p1, const char* p2)
121{
122    p1 += p2;
123    return p1;
124}
125static inline path operator+(path p1, path::value_type p2)
126{
127    p1 += p2;
128    return p1;
129}
130
131// Disallow unsafe path append operations.
132template<typename T> static inline path operator/(path p1, T p2) = delete;
133template<typename T> static inline path operator+(path p1, T p2) = delete;
134
135// Disallow implicit std::string conversion for copy_file
136// to avoid locale-dependent encoding on Windows.
137static inline bool copy_file(const path& from, const path& to, copy_options options)
138{
139    return std::filesystem::copy_file(from, to, options);
140}
141
142/**
143 * Convert path object to a byte string. On POSIX, paths natively are byte
144 * strings, so this is trivial. On Windows, paths natively are Unicode, so an
145 * encoding step is necessary. The inverse of \ref PathToString is \ref
146 * PathFromString. The strings returned and parsed by these functions can be
147 * used to call POSIX APIs, and for roundtrip conversion, logging, and
148 * debugging.
149 *
150 * Because \ref PathToString and \ref PathFromString functions don't specify an
151 * encoding, they are meant to be used internally, not externally. They are not
152 * appropriate to use in applications requiring UTF-8, where
153 * fs::path::u8string() / fs::path::utf8string() and fs::u8path() methods should be used instead. Other
154 * applications could require still different encodings. For example, JSON, XML,
155 * or URI applications might prefer to use higher-level escapes (\uXXXX or
156 * &XXXX; or %XX) instead of multibyte encoding. Rust, Python, Java applications
157 * may require encoding paths with their respective UTF-8 derivatives WTF-8,
158 * PEP-383, and CESU-8 (see https://en.wikipedia.org/wiki/UTF-8#Derivatives).
159 */
160static inline std::string PathToString(const path& path)
161{
162    // Implementation note: On Windows, the std::filesystem::path(string)
163    // constructor and std::filesystem::path::string() method are not safe to
164    // use here, because these methods encode the path using C++'s narrow
165    // multibyte encoding, which on Windows corresponds to the current "code
166    // page", which is unpredictable and typically not able to represent all
167    // valid paths. So fs::path::utf8string() and
168    // fs::u8path() functions are used instead on Windows. On
169    // POSIX, u8string/utf8string/u8path functions are not safe to use because paths are
170    // not always valid UTF-8, so plain string methods which do not transform
171    // the path there are used.
172#ifdef WIN32
173    return path.utf8string();
174#else
175    static_assert(std::is_same_v<path::string_type, std::string>, "PathToString not implemented on this platform");
176    return path.std::filesystem::path::string();
177#endif
178}
179
180/**
181 * Convert byte string to path object. Inverse of \ref PathToString.
182 */
183static inline path PathFromString(const std::string& string)
184{
185#ifdef WIN32
186    return u8path(string);
187#else
188    return std::filesystem::path(string);
189#endif
190}
191} // namespace fs
192
193/** Bridge operations to C stdio */
194namespace fsbridge {
195    using FopenFn = std::function<FILE*(const fs::path&, const char*)>;
196    FILE *fopen(const fs::path& p, const char *mode);
197
198    /**
199     * Helper function for joining two paths
200     *
201     * @param[in] base  Base path
202     * @param[in] path  Path to combine with base
203     * @returns path unchanged if it is an absolute path, otherwise returns base joined with path. Returns base unchanged if path is empty.
204     * @pre  Base path must be absolute
205     * @post Returned path will always be absolute
206     */
207    fs::path AbsPathJoin(const fs::path& base, const fs::path& path);
208
209    class FileLock
210    {
211    public:
212        FileLock() = delete;
213        FileLock(const FileLock&) = delete;
214        FileLock(FileLock&&) = delete;
215        explicit FileLock(const fs::path& file);
216        ~FileLock();
217        bool TryLock();
218        std::string GetReason() { return reason; }
219
220    private:
221        std::string reason;
222#ifndef WIN32
223        int fd = -1;
224#else
225        void* hFile = (void*)-1; // INVALID_HANDLE_VALUE
226#endif
227    };
228};
229
230// Disallow path operator<< formatting in tinyformat to avoid locale-dependent
231// encoding on windows.
232namespace tinyformat {
233template<> inline void formatValue(std::ostream&, const char*, const char*, int, const std::filesystem::path&) = delete;
234template<> inline void formatValue(std::ostream&, const char*, const char*, int, const fs::path&) = delete;
235} // namespace tinyformat
236
237#endif // BITCOIN_UTIL_FS_H
238