MySQL 9.1.0
Source Code Documentation
filesystem.h
Go to the documentation of this file.
1/*
2 Copyright (c) 2015, 2024, Oracle and/or its affiliates.
3
4 This program is free software; you can redistribute it and/or modify
5 it under the terms of the GNU General Public License, version 2.0,
6 as published by the Free Software Foundation.
7
8 This program is designed to work with certain software (including
9 but not limited to OpenSSL) that is licensed under separate terms,
10 as designated in a particular file or component or in included license
11 documentation. The authors of MySQL hereby grant you an additional
12 permission to link the program and your derivative works with the
13 separately licensed software that they have either included with
14 the program or referenced in the documentation.
15
16 This program is distributed in the hope that it will be useful,
17 but WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 GNU General Public License for more details.
20
21 You should have received a copy of the GNU General Public License
22 along with this program; if not, write to the Free Software
23 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
24*/
25
26#ifndef MYSQL_HARNESS_FILESYSTEM_INCLUDED
27#define MYSQL_HARNESS_FILESYSTEM_INCLUDED
28
29#include "harness_export.h"
30
31#include <memory>
32#include <ostream>
33#include <stdexcept>
34#include <string>
35#include <string_view>
36#include <system_error>
37#include <vector>
38
39#ifndef _WIN32
40#include <fcntl.h>
41#endif
42
45
46namespace mysql_harness {
47
48/**
49 * @defgroup Filesystem Platform-independent file system operations
50 *
51 * This module contain platform-independent file system operations.
52 */
53
54/**
55 * Class representing a path in a file system.
56 *
57 * @ingroup Filesystem
58 *
59 * Paths are used to access files in the file system and can be either
60 * relative or absolute. Absolute paths have a slash (`/`) first in
61 * the path, otherwise, the path is relative.
62 */
63class HARNESS_EXPORT Path {
64 friend std::ostream &operator<<(std::ostream &out, const Path &path) {
65 out << path.path_;
66 return out;
67 }
68
69 public:
70 /**
71 * Enum used to identify file types.
72 */
73
74 enum class FileType {
75 /** An error occurred when trying to get file type, but it is *not*
76 * that the file was not found. */
77 STATUS_ERROR,
78
79 /** Empty path was given */
80 EMPTY_PATH,
81
82 /** The file was not found. */
83 FILE_NOT_FOUND,
84
85 /** The file is a regular file. */
86 REGULAR_FILE,
87
88 /** The file is a directory. */
89 DIRECTORY_FILE,
90
91 /** The file is a symbolic link. */
92 SYMLINK_FILE,
93
94 /** The file is a block device */
95 BLOCK_FILE,
96
97 /** The file is a character device */
98 CHARACTER_FILE,
99
100 /** The file is a FIFO */
101 FIFO_FILE,
102
103 /** The file is a UNIX socket */
104 SOCKET_FILE,
105
106 /** The type of the file is unknown, either because it was not
107 * fetched yet or because stat(2) reported something else than the
108 * above. */
109 TYPE_UNKNOWN,
110 };
111
112 friend HARNESS_EXPORT std::ostream &operator<<(std::ostream &out,
113 FileType type);
114
115 Path() noexcept;
116
117 /**
118 * Construct a path
119 *
120 * @param path Non-empty string denoting the path.
121 * @throws std::invalid_argument
122 */
123 Path(std::string path);
124
125 Path(std::string_view path) : Path(std::string(path)) {}
126 Path(const char *path) : Path(std::string(path)) {}
127
128 /**
129 * Create a path from directory, basename, and extension.
130 */
131 static Path make_path(const Path &directory, const std::string &basename,
132 const std::string &extension);
133
134 bool operator==(const Path &rhs) const;
135 bool operator!=(const Path &rhs) const { return !(*this == rhs); }
136
137 /**
138 * Path ordering operator.
139 *
140 * This is mainly used for ordered containers. The paths are ordered
141 * lexicographically.
142 */
143 bool operator<(const Path &rhs) const;
144
145 /**
146 * Get the file type.
147 *
148 * The file type is normally cached so if the file type under a path
149 * changes it is necessary to force a refresh.
150 *
151 * @param refresh Set to `true` if the file type should be
152 * refreshed, default to `false`.
153 *
154 * @return The type of the file.
155 */
156 FileType type(bool refresh = false) const;
157
158 /**
159 * Check if the file is a directory.
160 */
161 bool is_directory() const;
162
163 /**
164 * Check if the file is a regular file.
165 */
166 bool is_regular() const;
167
168 /**
169 * Check if the path is absolute or not
170 *
171 * The path is considered absolute if it starts with one of:
172 * Unix: '/'
173 * Windows: '/' or '\' or '.:' (where . is any character)
174 * else:
175 * it's considered relative (empty path is also relative in such respect)
176 */
177 bool is_absolute() const;
178
179 /**
180 * Check if path exists
181 */
182 bool exists() const;
183
184 /*
185 * @brief Checks if path exists and can be opened for reading.
186 *
187 * @return true if path exists and can be opened for reading,
188 * false otherwise.
189 */
190 bool is_readable() const;
191
192 /**
193 * Get the directory name of the path.
194 *
195 * This will strip the last component of a path, assuming that the
196 * what remains is a directory name. If the path is a relative path
197 * that do not contain any directory separators, a dot will be
198 * returned (denoting the current directory).
199 *
200 * @note No checking of the components are done, this is just simple
201 * path manipulation.
202 *
203 * @return A new path object representing the directory portion of
204 * the path.
205 */
206 Path dirname() const;
207
208 /**
209 * Get the basename of the path.
210 *
211 * Return the basename of the path: the path without the directory
212 * portion.
213 *
214 * @note No checking of the components are done, this is just simple
215 * path manipulation.
216 *
217 * @return A new path object representing the basename of the path.
218 * the path.
219 */
220 Path basename() const;
221
222 /**
223 * Append a path component to the current path.
224 *
225 * This function will append a path component to the path using the
226 * appropriate directory separator.
227 *
228 * @param other Path component to append to the path.
229 */
230 void append(const Path &other);
231
232 /**
233 * Join two path components to form a new path.
234 *
235 * This function will join the two path components using a
236 * directory separator.
237 *
238 * @note This will return a new `Path` object. If you want to modify
239 * the existing path object, you should use `append` instead.
240 *
241 * @param other Path component to be appended to the path
242 */
243 Path join(const Path &other) const;
244
245 /**
246 * Returns the canonical form of the path, resolving relative paths.
247 */
248 Path real_path() const;
249
250 /**
251 * Get a C-string representation to the path.
252 *
253 * @note This will return a pointer to the internal representation
254 * of the path and hence will become a dangling pointer when the
255 * `Path` object is destroyed.
256 *
257 * @return Pointer to a null-terminated C-string.
258 */
259 const char *c_str() const { return path_.c_str(); }
260
261 /**
262 * Get a string representation of the path.
263 *
264 * @return Instance of std::string containing the path.
265 */
266 const std::string &str() const noexcept { return path_; }
267
268 /**
269 * Test if path is set
270 *
271 * @return Test result
272 */
273 bool is_set() const noexcept { return (type_ != FileType::EMPTY_PATH); }
274
275 /**
276 * Directory separator string.
277 *
278 * @note This is platform-dependent and defined in the appropriate
279 * source file.
280 */
281 static const char *const directory_separator;
282
283 /**
284 * Root directory string.
285 *
286 * @note This is platform-dependent and defined in the appropriate
287 * source file.
288 */
289 static const char *const root_directory;
290
291 operator bool() const noexcept { return is_set(); }
292
293 private:
294 void validate_non_empty_path() const; // throws std::invalid_argument
295
296 std::string path_;
298};
299
300/**
301 * Class representing a directory in a file system.
302 *
303 * @ingroup Filesystem
304 *
305 * In addition to being a refinement of `Path`, it also have functions
306 * that make it act like a container of paths and support iterating
307 * over the entries in a directory.
308 *
309 * An example of how it could be used is:
310 * @code
311 * for (auto&& entry: Directory(path))
312 * std::cout << entry << std::endl;
313 * @endcode
314 */
315class HARNESS_EXPORT Directory : public Path {
316 public:
317 /**
318 * Directory iterator for iterating over directory entries.
319 *
320 * A directory iterator is an input iterator.
321 */
322 class HARNESS_EXPORT DirectoryIterator {
323 friend class Directory;
324
325 public:
327 using iterator_category = std::input_iterator_tag;
328 using difference_type = std::ptrdiff_t;
331
333 const std::string &pattern = std::string());
334
335 // Create an end iterator
337
338 /**
339 * Destructor.
340 *
341 * @note We need this *declared* because the default constructor
342 * try to generate a default constructor for shared_ptr on State
343 * below, which does not work since it is not visible. The
344 * destructor need to be *defined* in the corresponding .cc file
345 * since the State type is visible there (but you can use a
346 * default definition).
347 */
349
350 // We need these since the default move/copy constructor is
351 // deleted when you define a destructor.
352#if !defined(_MSC_VER) || (_MSC_VER >= 1900)
355#endif
356
357 /** Standard iterator operators */
358 /** @{ */
359 Path operator*() const;
361 Path operator->() { return this->operator*(); }
362 bool operator!=(const DirectoryIterator &other) const;
363
364 // This avoids C2678 (no binary operator found) in MSVC,
365 // MSVC's std::copy implementation (used by TestFilesystem) uses operator==
366 // (while GCC's implementation uses operator!=).
367 bool operator==(const DirectoryIterator &other) const {
368 return !(this->operator!=(other));
369 }
370 /** @} */
371
372 private:
373 /**
374 * Path to the root of the directory
375 */
376 const Path path_;
377
378 /**
379 * Pattern that matches entries iterated over.
380 */
381 std::string pattern_;
382
383 /*
384 * Platform-dependent container for iterator state.
385 *
386 * The definition of this class is different for different
387 * platforms, meaning that it is not defined here at all but
388 * rather in the corresponding `filesystem-<platform>.cc` file.
389 *
390 * The directory iterator is the most critical piece since it holds
391 * an iteration state for the platform: something that requires
392 * different types on the platforms.
393 */
394 class State;
395 std::shared_ptr<State> state_;
396 };
397
398 /**
399 * Construct a directory instance.
400 *
401 * Construct a directory instance in different ways depending on the
402 * version of the constructor used.
403 */
404 Directory(const std::string &path) // NOLINT(runtime/explicit)
405 : Path(path) {} // throws std::invalid_argument
406
407 /** @overload */ // throws std::invalid_argument
408 Directory(const Path &path); // NOLINT(runtime/explicit)
409
410 Directory(const Directory &) = default;
411 Directory &operator=(const Directory &) = default;
413
414 /**
415 * Iterator to first entry.
416 *
417 * @return Returns an iterator pointing to the first entry.
418 */
420
421 DirectoryIterator begin() const { return cbegin(); }
422
423 /**
424 * Constant iterator to first entry.
425 *
426 * @return Returns a constant iterator pointing to the first entry.
427 */
428 DirectoryIterator cbegin() const;
429
430 /**
431 * Iterator past-the-end of entries.
432 *
433 * @return Returns an iterator pointing *past-the-end* of the entries.
434 */
435 DirectoryIterator end();
436
437 DirectoryIterator end() const { return cend(); }
438
439 /**
440 * Constant iterator past-the-end of entries.
441 *
442 * @return Returns a constant iterator pointing *past-the-end* of the entries.
443 */
444 DirectoryIterator cend() const;
445
446 /**
447 * Check if the directory is empty.
448 *
449 * @retval true Directory is empty.
450 * @retval false Directory is no empty.
451 */
452 bool is_empty() const;
453
454 /**
455 * Recursively list all paths in a directory.
456 *
457 * Recursively create a list of relative paths from a directory. Path will
458 * be relative to the given directory. Empty directories are also listed.
459 *
460 * @return Recursive list of paths from a directory.
461 */
462 std::vector<Path> list_recursive() const;
463
464 /**
465 * Iterate over entries matching a glob.
466 */
467 DirectoryIterator glob(const std::string &glob);
468};
469
470////////////////////////////////////////////////////////////////////////////////
471//
472// Utility free functions
473//
474////////////////////////////////////////////////////////////////////////////////
475
476/** @brief Removes a directory.
477 *
478 * @ingroup Filesystem
479 *
480 * @param dir path of the directory to be removed; this directory must be empty
481 *
482 * @return void on success, error_code on failure
483 */
484HARNESS_EXPORT
486 const std::string &dir) noexcept;
487
488/** @brief Removes a file.
489 *
490 * @ingroup Filesystem
491 *
492 * @param path of the file to be removed
493 *
494 * @return void on success, error_code on failure
495 */
496HARNESS_EXPORT
498 const std::string &path) noexcept;
499
500/** @brief Removes directory and all its contents.
501 *
502 * @ingroup Filesystem
503 *
504 * @param dir path of the directory to be removed
505 *
506 * @return void on success, error_code on failure
507 */
508HARNESS_EXPORT
510 const std::string &dir) noexcept;
511
512/** @brief Creates a temporary directory with partially-random name and returns
513 * its path.
514 *
515 * Creates a directory with a name of form {prefix}-{6 random alphanumerals}.
516 * For example, a possible directory name created by a call to
517 * get_tmp_dir("foo") might be: foo-3f9x0z
518 *
519 * Such directory is usually meant to be used as a temporary directory (thus the
520 * "_tmp_" in the name of this function).
521 *
522 * @ingroup Filesystem
523 *
524 * @param name name to be used as a directory name prefix
525 *
526 * @return path to the created directory
527 *
528 * @throws std::runtime_error if operation failed
529 */
530HARNESS_EXPORT
531std::string get_tmp_dir(const std::string &name = "router");
532
533// TODO: description
534// TODO: move to some other place?
535HARNESS_EXPORT
536std::string get_plugin_dir(const std::string &runtime_dir);
537
538HARNESS_EXPORT
539std::string get_tests_data_dir(const std::string &runtime_dir);
540
541#ifndef _WIN32
542using perm_mode = mode_t;
543HARNESS_EXPORT
545#else
546using perm_mode = int;
547HARNESS_EXPORT
549#endif
550
551/** @brief Creates a directory
552 * *
553 * @param dir name (or path) of the directory to create
554 * @param mode permission mode for the created directory
555 * @param recursive if true then imitate unix `mkdir -p` recursively
556 * creating parent directories if needed
557 * @retval 0 operation succeeded
558 * @retval -1 operation failed because of wrong parameters
559 * @retval > 0 errno for failure to mkdir() system call
560 */
561HARNESS_EXPORT
562int mkdir(const std::string &dir, perm_mode mode, bool recursive = false);
563
564/**
565 * Changes file access permissions to be fully accessible by all users.
566 *
567 * On Unix, the function sets file permission mask to 777.
568 * On Windows, Everyone group is granted full access to the file.
569 *
570 * @param[in] file_name File name.
571 *
572 * @throw std::exception Failed to change file permissions.
573 */
574void HARNESS_EXPORT make_file_public(const std::string &file_name);
575
576#ifdef _WIN32
577/**
578 * Changes file access permissions to be readable by all users.
579 *
580 * On Windows, Everyone group is granted read access to the file.
581 *
582 * @param[in] file_name File name.
583 *
584 * @throw std::exception Failed to change file permissions.
585 */
586void make_file_readable_for_everyone(const std::string &file_name);
587#endif
588
589/**
590 * Changes file access permissions to be accessible only by a limited set of
591 * users.
592 *
593 * On Unix, the function sets file permission mask to 600.
594 * On Windows, all permissions to this file are removed for Everyone group,
595 * LocalService account gets read (and optionally write) access.
596 *
597 * @param[in] file_name File name.
598 * @param[in] read_only_for_local_service Weather the LocalService user on
599 * Windows should get only the read access (if false will grant write access
600 * too). Not used on non-Windows.
601 *
602 * @throw std::exception Failed to change file permissions.
603 */
604void HARNESS_EXPORT
605make_file_private(const std::string &file_name,
606 const bool read_only_for_local_service = true);
607
608/**
609 * Changes file access permissions to be read only.
610 *
611 * On Unix, the function sets file permission mask to 555.
612 * On Windows, all permissions to this file are read access only for Everyone
613 * group, LocalService account gets read access.
614 *
615 * @param[in] file_name File name.
616 *
617 * @throw std::exception Failed to change file permissions.
618 */
619void HARNESS_EXPORT make_file_readonly(const std::string &file_name);
620
621/**
622 * Verifies access permissions of a file.
623 *
624 * On Unix systems it throws if file's permissions differ from 600.
625 * On Windows it throws if file can be accessed by Everyone group.
626 *
627 * @param[in] file_name File to be verified.
628 *
629 * @throw std::exception File access rights are too permissive or
630 * an error occurred.
631 * @throw std::system_error OS and/or filesystem doesn't support file
632 * permissions.
633 */
634
635void HARNESS_EXPORT check_file_access_rights(const std::string &file_name);
636
637} // namespace mysql_harness
638
639#endif /* MYSQL_HARNESS_FILESYSTEM_INCLUDED */
Definition: filesystem-posix.cc:124
Directory iterator for iterating over directory entries.
Definition: filesystem.h:322
const Path path_
Path to the root of the directory.
Definition: filesystem.h:376
std::input_iterator_tag iterator_category
Definition: filesystem.h:327
Path operator->()
Definition: filesystem.h:361
DirectoryIterator(const DirectoryIterator &)
bool operator==(const DirectoryIterator &other) const
Definition: filesystem.h:367
std::shared_ptr< State > state_
Definition: filesystem.h:394
std::ptrdiff_t difference_type
Definition: filesystem.h:328
std::string pattern_
Pattern that matches entries iterated over.
Definition: filesystem.h:381
Class representing a directory in a file system.
Definition: filesystem.h:315
DirectoryIterator end() const
Definition: filesystem.h:437
DirectoryIterator begin() const
Definition: filesystem.h:421
Directory(const Directory &)=default
Directory & operator=(const Directory &)=default
Directory(const std::string &path)
Construct a directory instance.
Definition: filesystem.h:404
Class representing a path in a file system.
Definition: filesystem.h:63
std::string path_
Definition: filesystem.h:296
const char * c_str() const
Get a C-string representation to the path.
Definition: filesystem.h:259
FileType type_
Definition: filesystem.h:297
bool is_set() const noexcept
Test if path is set.
Definition: filesystem.h:273
bool operator!=(const Path &rhs) const
Definition: filesystem.h:135
FileType
Enum used to identify file types.
Definition: filesystem.h:74
static const char *const root_directory
Root directory string.
Definition: filesystem.h:289
static const char *const directory_separator
Directory separator string.
Definition: filesystem.h:281
const std::string & str() const noexcept
Get a string representation of the path.
Definition: filesystem.h:266
friend std::ostream & operator<<(std::ostream &out, const Path &path)
Definition: filesystem.h:64
Path(const char *path)
Definition: filesystem.h:126
Definition: expected.h:286
HARNESS_EXPORT stdx::expected< void, std::error_code > delete_file(const std::string &path) noexcept
Removes a file.
Definition: filesystem-posix.cc:317
HARNESS_EXPORT stdx::expected< void, std::error_code > delete_dir(const std::string &dir) noexcept
Removes a directory.
Definition: filesystem-posix.cc:308
HARNESS_EXPORT std::string get_tmp_dir(const std::string &name="router")
Creates a temporary directory with partially-random name and returns its path.
Definition: filesystem-posix.cc:326
HARNESS_EXPORT stdx::expected< void, std::error_code > delete_dir_recursive(const std::string &dir) noexcept
Removes directory and all its contents.
Definition: filesystem.cc:247
bool operator!=(const my_thread_handle &a, const my_thread_handle &b)
Definition: my_thread.h:158
bool operator==(const my_thread_handle &a, const my_thread_handle &b)
Definition: my_thread.h:151
static char * path
Definition: mysqldump.cc:149
std::string dir
Double write files location.
Definition: buf0dblwr.cc:77
std::string file_name(Log_file_id file_id)
Provides name of the log file with the given file id, e.g.
Definition: log0pre_8_0_30.cc:94
std::string dirname(const std::string &path)
Definition: utilities.cc:38
std::string basename(const std::string &path)
Definition: utilities.cc:46
Definition: common.h:42
void HARNESS_EXPORT make_file_readonly(const std::string &file_name)
Changes file access permissions to be read only.
Definition: filesystem-posix.cc:371
HARNESS_EXPORT std::string get_tests_data_dir(const std::string &runtime_dir)
Definition: filesystem.cc:285
HARNESS_EXPORT int mkdir(const std::string &dir, perm_mode mode, bool recursive=false)
Creates a directory *.
Definition: filesystem.cc:330
void HARNESS_EXPORT check_file_access_rights(const std::string &file_name)
Verifies access permissions of a file.
Definition: filesystem.cc:338
void HARNESS_EXPORT make_file_private(const std::string &file_name, const bool read_only_for_local_service=true)
Changes file access permissions to be accessible only by a limited set of users.
Definition: filesystem-posix.cc:360
HARNESS_EXPORT std::string get_plugin_dir(const std::string &runtime_dir)
Definition: filesystem.cc:267
void HARNESS_EXPORT make_file_public(const std::string &file_name)
Changes file access permissions to be fully accessible by all users.
Definition: filesystem-posix.cc:351
std::string join(const detail::range auto &rng, std::string_view delim)
join elements of a range into a string separated by a delimiter.
Definition: string.h:74
mode_t perm_mode
Definition: filesystem.h:542
void make_file_readable_for_everyone(const std::string &file_name)
Definition: filesystem-windows.cc:459
HARNESS_EXPORT const perm_mode kStrictDirectoryPerm
Definition: filesystem-posix.cc:61
std::ostream & operator<<(std::ostream &out, Path::FileType type)
Definition: filesystem.cc:168
const char * begin(const char *const c)
Definition: base64.h:44
constexpr bool operator<(const address_v4 &a, const address_v4 &b) noexcept
Definition: internet.h:166
Cursor end()
A past-the-end Cursor.
Definition: rules_table_service.cc:192
Definition: gcs_xcom_synode.h:64
mode
Definition: file_handle.h:61
static int exists(node_address *name, node_list const *nodes, u_int with_uid)
Definition: node_list.cc:106
bool_t is_set(node_set set, node_no i)
Definition: node_set.cc:230
required string type
Definition: replication_group_member_actions.proto:34
Ssl_acceptor_context_property_type & operator++(Ssl_acceptor_context_property_type &property_type)
Increment operator for Ssl_acceptor_context_type Used by iterator.
Definition: ssl_acceptor_context_data.cc:273
case opt name
Definition: sslopt-case.h:29