blob: 156250faabe0f10f33f3e602abc9ad91866d6ea2 [file] [log] [blame]
Andrew Scull5e1ddfa2018-08-14 10:06:54 +01001//===- llvm/Support/FileSystem.h - File System OS Concept -------*- C++ -*-===//
2//
Andrew Walbran16937d02019-10-22 13:54:20 +01003// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
Andrew Scull5e1ddfa2018-08-14 10:06:54 +01006//
7//===----------------------------------------------------------------------===//
8//
9// This file declares the llvm::sys::fs namespace. It is designed after
10// TR2/boost filesystem (v3), but modified to remove exception handling and the
11// path class.
12//
13// All functions return an error_code and their actual work via the last out
14// argument. The out argument is defined if and only if errc::success is
15// returned. A function may return any error code in the generic or system
16// category. However, they shall be equivalent to any error conditions listed
17// in each functions respective documentation if the condition applies. [ note:
18// this does not guarantee that error_code will be in the set of explicitly
19// listed codes, but it does guarantee that if any of the explicitly listed
20// errors occur, the correct error_code will be used ]. All functions may
21// return errc::not_enough_memory if there is not enough memory to complete the
22// operation.
23//
24//===----------------------------------------------------------------------===//
25
26#ifndef LLVM_SUPPORT_FILESYSTEM_H
27#define LLVM_SUPPORT_FILESYSTEM_H
28
29#include "llvm/ADT/SmallString.h"
30#include "llvm/ADT/StringRef.h"
31#include "llvm/ADT/Twine.h"
Andrew Scullcdfcccc2018-10-05 20:58:37 +010032#include "llvm/Config/llvm-config.h"
Andrew Scull5e1ddfa2018-08-14 10:06:54 +010033#include "llvm/Support/Chrono.h"
34#include "llvm/Support/Error.h"
35#include "llvm/Support/ErrorHandling.h"
36#include "llvm/Support/ErrorOr.h"
37#include "llvm/Support/MD5.h"
38#include <cassert>
39#include <cstdint>
40#include <ctime>
41#include <memory>
42#include <stack>
43#include <string>
44#include <system_error>
45#include <tuple>
46#include <vector>
47
48#ifdef HAVE_SYS_STAT_H
49#include <sys/stat.h>
50#endif
51
52namespace llvm {
53namespace sys {
54namespace fs {
55
Andrew Scullcdfcccc2018-10-05 20:58:37 +010056#if defined(_WIN32)
57// A Win32 HANDLE is a typedef of void*
58using file_t = void *;
59#else
60using file_t = int;
61#endif
62
63extern const file_t kInvalidFile;
64
Andrew Scull5e1ddfa2018-08-14 10:06:54 +010065/// An enumeration for the file system's view of the type.
66enum class file_type {
67 status_error,
68 file_not_found,
69 regular_file,
70 directory_file,
71 symlink_file,
72 block_file,
73 character_file,
74 fifo_file,
75 socket_file,
76 type_unknown
77};
78
79/// space_info - Self explanatory.
80struct space_info {
81 uint64_t capacity;
82 uint64_t free;
83 uint64_t available;
84};
85
86enum perms {
87 no_perms = 0,
88 owner_read = 0400,
89 owner_write = 0200,
90 owner_exe = 0100,
91 owner_all = owner_read | owner_write | owner_exe,
92 group_read = 040,
93 group_write = 020,
94 group_exe = 010,
95 group_all = group_read | group_write | group_exe,
96 others_read = 04,
97 others_write = 02,
98 others_exe = 01,
99 others_all = others_read | others_write | others_exe,
100 all_read = owner_read | group_read | others_read,
101 all_write = owner_write | group_write | others_write,
102 all_exe = owner_exe | group_exe | others_exe,
103 all_all = owner_all | group_all | others_all,
104 set_uid_on_exe = 04000,
105 set_gid_on_exe = 02000,
106 sticky_bit = 01000,
107 all_perms = all_all | set_uid_on_exe | set_gid_on_exe | sticky_bit,
108 perms_not_known = 0xFFFF
109};
110
111// Helper functions so that you can use & and | to manipulate perms bits:
112inline perms operator|(perms l, perms r) {
113 return static_cast<perms>(static_cast<unsigned short>(l) |
114 static_cast<unsigned short>(r));
115}
116inline perms operator&(perms l, perms r) {
117 return static_cast<perms>(static_cast<unsigned short>(l) &
118 static_cast<unsigned short>(r));
119}
120inline perms &operator|=(perms &l, perms r) {
121 l = l | r;
122 return l;
123}
124inline perms &operator&=(perms &l, perms r) {
125 l = l & r;
126 return l;
127}
128inline perms operator~(perms x) {
129 // Avoid UB by explicitly truncating the (unsigned) ~ result.
130 return static_cast<perms>(
131 static_cast<unsigned short>(~static_cast<unsigned short>(x)));
132}
133
134class UniqueID {
135 uint64_t Device;
136 uint64_t File;
137
138public:
139 UniqueID() = default;
140 UniqueID(uint64_t Device, uint64_t File) : Device(Device), File(File) {}
141
142 bool operator==(const UniqueID &Other) const {
143 return Device == Other.Device && File == Other.File;
144 }
145 bool operator!=(const UniqueID &Other) const { return !(*this == Other); }
146 bool operator<(const UniqueID &Other) const {
147 return std::tie(Device, File) < std::tie(Other.Device, Other.File);
148 }
149
150 uint64_t getDevice() const { return Device; }
151 uint64_t getFile() const { return File; }
152};
153
154/// Represents the result of a call to directory_iterator::status(). This is a
155/// subset of the information returned by a regular sys::fs::status() call, and
156/// represents the information provided by Windows FileFirstFile/FindNextFile.
157class basic_file_status {
158protected:
159 #if defined(LLVM_ON_UNIX)
160 time_t fs_st_atime = 0;
161 time_t fs_st_mtime = 0;
Andrew Walbran16937d02019-10-22 13:54:20 +0100162 uint32_t fs_st_atime_nsec = 0;
163 uint32_t fs_st_mtime_nsec = 0;
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100164 uid_t fs_st_uid = 0;
165 gid_t fs_st_gid = 0;
166 off_t fs_st_size = 0;
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100167 #elif defined (_WIN32)
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100168 uint32_t LastAccessedTimeHigh = 0;
169 uint32_t LastAccessedTimeLow = 0;
170 uint32_t LastWriteTimeHigh = 0;
171 uint32_t LastWriteTimeLow = 0;
172 uint32_t FileSizeHigh = 0;
173 uint32_t FileSizeLow = 0;
174 #endif
175 file_type Type = file_type::status_error;
176 perms Perms = perms_not_known;
177
178public:
179 basic_file_status() = default;
180
181 explicit basic_file_status(file_type Type) : Type(Type) {}
182
183 #if defined(LLVM_ON_UNIX)
Andrew Walbran16937d02019-10-22 13:54:20 +0100184 basic_file_status(file_type Type, perms Perms, time_t ATime,
185 uint32_t ATimeNSec, time_t MTime, uint32_t MTimeNSec,
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100186 uid_t UID, gid_t GID, off_t Size)
Andrew Walbran16937d02019-10-22 13:54:20 +0100187 : fs_st_atime(ATime), fs_st_mtime(MTime),
188 fs_st_atime_nsec(ATimeNSec), fs_st_mtime_nsec(MTimeNSec),
189 fs_st_uid(UID), fs_st_gid(GID),
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100190 fs_st_size(Size), Type(Type), Perms(Perms) {}
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100191#elif defined(_WIN32)
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100192 basic_file_status(file_type Type, perms Perms, uint32_t LastAccessTimeHigh,
193 uint32_t LastAccessTimeLow, uint32_t LastWriteTimeHigh,
194 uint32_t LastWriteTimeLow, uint32_t FileSizeHigh,
195 uint32_t FileSizeLow)
196 : LastAccessedTimeHigh(LastAccessTimeHigh),
197 LastAccessedTimeLow(LastAccessTimeLow),
198 LastWriteTimeHigh(LastWriteTimeHigh),
199 LastWriteTimeLow(LastWriteTimeLow), FileSizeHigh(FileSizeHigh),
200 FileSizeLow(FileSizeLow), Type(Type), Perms(Perms) {}
201 #endif
202
203 // getters
204 file_type type() const { return Type; }
205 perms permissions() const { return Perms; }
Andrew Walbran16937d02019-10-22 13:54:20 +0100206
207 /// The file access time as reported from the underlying file system.
208 ///
209 /// Also see comments on \c getLastModificationTime() related to the precision
210 /// of the returned value.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100211 TimePoint<> getLastAccessedTime() const;
Andrew Walbran16937d02019-10-22 13:54:20 +0100212
213 /// The file modification time as reported from the underlying file system.
214 ///
215 /// The returned value allows for nanosecond precision but the actual
216 /// resolution is an implementation detail of the underlying file system.
217 /// There is no guarantee for what kind of resolution you can expect, the
218 /// resolution can differ across platforms and even across mountpoints on the
219 /// same machine.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100220 TimePoint<> getLastModificationTime() const;
221
222 #if defined(LLVM_ON_UNIX)
223 uint32_t getUser() const { return fs_st_uid; }
224 uint32_t getGroup() const { return fs_st_gid; }
225 uint64_t getSize() const { return fs_st_size; }
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100226 #elif defined (_WIN32)
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100227 uint32_t getUser() const {
228 return 9999; // Not applicable to Windows, so...
229 }
230
231 uint32_t getGroup() const {
232 return 9999; // Not applicable to Windows, so...
233 }
234
235 uint64_t getSize() const {
236 return (uint64_t(FileSizeHigh) << 32) + FileSizeLow;
237 }
238 #endif
239
240 // setters
241 void type(file_type v) { Type = v; }
242 void permissions(perms p) { Perms = p; }
243};
244
245/// Represents the result of a call to sys::fs::status().
246class file_status : public basic_file_status {
247 friend bool equivalent(file_status A, file_status B);
248
249 #if defined(LLVM_ON_UNIX)
250 dev_t fs_st_dev = 0;
251 nlink_t fs_st_nlinks = 0;
252 ino_t fs_st_ino = 0;
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100253 #elif defined (_WIN32)
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100254 uint32_t NumLinks = 0;
255 uint32_t VolumeSerialNumber = 0;
256 uint32_t FileIndexHigh = 0;
257 uint32_t FileIndexLow = 0;
258 #endif
259
260public:
261 file_status() = default;
262
263 explicit file_status(file_type Type) : basic_file_status(Type) {}
264
265 #if defined(LLVM_ON_UNIX)
266 file_status(file_type Type, perms Perms, dev_t Dev, nlink_t Links, ino_t Ino,
Andrew Walbran16937d02019-10-22 13:54:20 +0100267 time_t ATime, uint32_t ATimeNSec,
268 time_t MTime, uint32_t MTimeNSec,
269 uid_t UID, gid_t GID, off_t Size)
270 : basic_file_status(Type, Perms, ATime, ATimeNSec, MTime, MTimeNSec,
271 UID, GID, Size),
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100272 fs_st_dev(Dev), fs_st_nlinks(Links), fs_st_ino(Ino) {}
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100273 #elif defined(_WIN32)
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100274 file_status(file_type Type, perms Perms, uint32_t LinkCount,
275 uint32_t LastAccessTimeHigh, uint32_t LastAccessTimeLow,
276 uint32_t LastWriteTimeHigh, uint32_t LastWriteTimeLow,
277 uint32_t VolumeSerialNumber, uint32_t FileSizeHigh,
278 uint32_t FileSizeLow, uint32_t FileIndexHigh,
279 uint32_t FileIndexLow)
280 : basic_file_status(Type, Perms, LastAccessTimeHigh, LastAccessTimeLow,
281 LastWriteTimeHigh, LastWriteTimeLow, FileSizeHigh,
282 FileSizeLow),
283 NumLinks(LinkCount), VolumeSerialNumber(VolumeSerialNumber),
284 FileIndexHigh(FileIndexHigh), FileIndexLow(FileIndexLow) {}
285 #endif
286
287 UniqueID getUniqueID() const;
288 uint32_t getLinkCount() const;
289};
290
291/// @}
292/// @name Physical Operators
293/// @{
294
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100295/// Make \a path an absolute path.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100296///
297/// Makes \a path absolute using the \a current_directory if it is not already.
298/// An empty \a path will result in the \a current_directory.
299///
300/// /absolute/path => /absolute/path
301/// relative/../path => <current-directory>/relative/../path
302///
303/// @param path A path that is modified to be an absolute path.
Andrew Walbran16937d02019-10-22 13:54:20 +0100304void make_absolute(const Twine &current_directory, SmallVectorImpl<char> &path);
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100305
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100306/// Make \a path an absolute path.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100307///
308/// Makes \a path absolute using the current directory if it is not already. An
309/// empty \a path will result in the current directory.
310///
311/// /absolute/path => /absolute/path
312/// relative/../path => <current-directory>/relative/../path
313///
314/// @param path A path that is modified to be an absolute path.
315/// @returns errc::success if \a path has been made absolute, otherwise a
316/// platform-specific error_code.
317std::error_code make_absolute(SmallVectorImpl<char> &path);
318
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100319/// Create all the non-existent directories in path.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100320///
321/// @param path Directories to create.
322/// @returns errc::success if is_directory(path), otherwise a platform
323/// specific error_code. If IgnoreExisting is false, also returns
324/// error if the directory already existed.
325std::error_code create_directories(const Twine &path,
326 bool IgnoreExisting = true,
327 perms Perms = owner_all | group_all);
328
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100329/// Create the directory in path.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100330///
331/// @param path Directory to create.
332/// @returns errc::success if is_directory(path), otherwise a platform
333/// specific error_code. If IgnoreExisting is false, also returns
334/// error if the directory already existed.
335std::error_code create_directory(const Twine &path, bool IgnoreExisting = true,
336 perms Perms = owner_all | group_all);
337
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100338/// Create a link from \a from to \a to.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100339///
340/// The link may be a soft or a hard link, depending on the platform. The caller
341/// may not assume which one. Currently on windows it creates a hard link since
342/// soft links require extra privileges. On unix, it creates a soft link since
343/// hard links don't work on SMB file systems.
344///
345/// @param to The path to hard link to.
346/// @param from The path to hard link from. This is created.
347/// @returns errc::success if the link was created, otherwise a platform
348/// specific error_code.
349std::error_code create_link(const Twine &to, const Twine &from);
350
351/// Create a hard link from \a from to \a to, or return an error.
352///
353/// @param to The path to hard link to.
354/// @param from The path to hard link from. This is created.
355/// @returns errc::success if the link was created, otherwise a platform
356/// specific error_code.
357std::error_code create_hard_link(const Twine &to, const Twine &from);
358
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100359/// Collapse all . and .. patterns, resolve all symlinks, and optionally
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100360/// expand ~ expressions to the user's home directory.
361///
362/// @param path The path to resolve.
363/// @param output The location to store the resolved path.
364/// @param expand_tilde If true, resolves ~ expressions to the user's home
365/// directory.
366std::error_code real_path(const Twine &path, SmallVectorImpl<char> &output,
367 bool expand_tilde = false);
368
Andrew Walbran16937d02019-10-22 13:54:20 +0100369/// Expands ~ expressions to the user's home directory. On Unix ~user
370/// directories are resolved as well.
371///
372/// @param path The path to resolve.
373void expand_tilde(const Twine &path, SmallVectorImpl<char> &output);
374
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100375/// Get the current path.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100376///
377/// @param result Holds the current path on return.
378/// @returns errc::success if the current path has been stored in result,
379/// otherwise a platform-specific error_code.
380std::error_code current_path(SmallVectorImpl<char> &result);
381
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100382/// Set the current path.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100383///
384/// @param path The path to set.
385/// @returns errc::success if the current path was successfully set,
386/// otherwise a platform-specific error_code.
387std::error_code set_current_path(const Twine &path);
388
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100389/// Remove path. Equivalent to POSIX remove().
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100390///
391/// @param path Input path.
392/// @returns errc::success if path has been removed or didn't exist, otherwise a
393/// platform-specific error code. If IgnoreNonExisting is false, also
394/// returns error if the file didn't exist.
395std::error_code remove(const Twine &path, bool IgnoreNonExisting = true);
396
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100397/// Recursively delete a directory.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100398///
399/// @param path Input path.
400/// @returns errc::success if path has been removed or didn't exist, otherwise a
401/// platform-specific error code.
402std::error_code remove_directories(const Twine &path, bool IgnoreErrors = true);
403
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100404/// Rename \a from to \a to.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100405///
406/// Files are renamed as if by POSIX rename(), except that on Windows there may
407/// be a short interval of time during which the destination file does not
408/// exist.
409///
410/// @param from The path to rename from.
411/// @param to The path to rename to. This is created.
412std::error_code rename(const Twine &from, const Twine &to);
413
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100414/// Copy the contents of \a From to \a To.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100415///
416/// @param From The path to copy from.
417/// @param To The path to copy to. This is created.
418std::error_code copy_file(const Twine &From, const Twine &To);
419
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100420/// Copy the contents of \a From to \a To.
421///
422/// @param From The path to copy from.
423/// @param ToFD The open file descriptor of the destination file.
424std::error_code copy_file(const Twine &From, int ToFD);
425
426/// Resize path to size. File is resized as if by POSIX truncate().
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100427///
428/// @param FD Input file descriptor.
429/// @param Size Size to resize to.
430/// @returns errc::success if \a path has been resized to \a size, otherwise a
431/// platform-specific error_code.
432std::error_code resize_file(int FD, uint64_t Size);
433
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100434/// Compute an MD5 hash of a file's contents.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100435///
436/// @param FD Input file descriptor.
437/// @returns An MD5Result with the hash computed, if successful, otherwise a
438/// std::error_code.
439ErrorOr<MD5::MD5Result> md5_contents(int FD);
440
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100441/// Version of compute_md5 that doesn't require an open file descriptor.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100442ErrorOr<MD5::MD5Result> md5_contents(const Twine &Path);
443
444/// @}
445/// @name Physical Observers
446/// @{
447
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100448/// Does file exist?
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100449///
450/// @param status A basic_file_status previously returned from stat.
451/// @returns True if the file represented by status exists, false if it does
452/// not.
453bool exists(const basic_file_status &status);
454
455enum class AccessMode { Exist, Write, Execute };
456
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100457/// Can the file be accessed?
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100458///
459/// @param Path Input path.
460/// @returns errc::success if the path can be accessed, otherwise a
461/// platform-specific error_code.
462std::error_code access(const Twine &Path, AccessMode Mode);
463
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100464/// Does file exist?
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100465///
466/// @param Path Input path.
467/// @returns True if it exists, false otherwise.
468inline bool exists(const Twine &Path) {
469 return !access(Path, AccessMode::Exist);
470}
471
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100472/// Can we execute this file?
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100473///
474/// @param Path Input path.
475/// @returns True if we can execute it, false otherwise.
476bool can_execute(const Twine &Path);
477
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100478/// Can we write this file?
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100479///
480/// @param Path Input path.
481/// @returns True if we can write to it, false otherwise.
482inline bool can_write(const Twine &Path) {
483 return !access(Path, AccessMode::Write);
484}
485
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100486/// Do file_status's represent the same thing?
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100487///
488/// @param A Input file_status.
489/// @param B Input file_status.
490///
491/// assert(status_known(A) || status_known(B));
492///
493/// @returns True if A and B both represent the same file system entity, false
494/// otherwise.
495bool equivalent(file_status A, file_status B);
496
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100497/// Do paths represent the same thing?
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100498///
499/// assert(status_known(A) || status_known(B));
500///
501/// @param A Input path A.
502/// @param B Input path B.
503/// @param result Set to true if stat(A) and stat(B) have the same device and
504/// inode (or equivalent).
505/// @returns errc::success if result has been successfully set, otherwise a
506/// platform-specific error_code.
507std::error_code equivalent(const Twine &A, const Twine &B, bool &result);
508
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100509/// Simpler version of equivalent for clients that don't need to
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100510/// differentiate between an error and false.
511inline bool equivalent(const Twine &A, const Twine &B) {
512 bool result;
513 return !equivalent(A, B, result) && result;
514}
515
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100516/// Is the file mounted on a local filesystem?
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100517///
518/// @param path Input path.
519/// @param result Set to true if \a path is on fixed media such as a hard disk,
520/// false if it is not.
521/// @returns errc::success if result has been successfully set, otherwise a
522/// platform specific error_code.
523std::error_code is_local(const Twine &path, bool &result);
524
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100525/// Version of is_local accepting an open file descriptor.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100526std::error_code is_local(int FD, bool &result);
527
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100528/// Simpler version of is_local for clients that don't need to
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100529/// differentiate between an error and false.
530inline bool is_local(const Twine &Path) {
531 bool Result;
532 return !is_local(Path, Result) && Result;
533}
534
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100535/// Simpler version of is_local accepting an open file descriptor for
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100536/// clients that don't need to differentiate between an error and false.
537inline bool is_local(int FD) {
538 bool Result;
539 return !is_local(FD, Result) && Result;
540}
541
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100542/// Does status represent a directory?
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100543///
544/// @param Path The path to get the type of.
545/// @param Follow For symbolic links, indicates whether to return the file type
546/// of the link itself, or of the target.
547/// @returns A value from the file_type enumeration indicating the type of file.
548file_type get_file_type(const Twine &Path, bool Follow = true);
549
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100550/// Does status represent a directory?
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100551///
552/// @param status A basic_file_status previously returned from status.
553/// @returns status.type() == file_type::directory_file.
554bool is_directory(const basic_file_status &status);
555
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100556/// Is path a directory?
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100557///
558/// @param path Input path.
559/// @param result Set to true if \a path is a directory (after following
560/// symlinks, false if it is not. Undefined otherwise.
561/// @returns errc::success if result has been successfully set, otherwise a
562/// platform-specific error_code.
563std::error_code is_directory(const Twine &path, bool &result);
564
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100565/// Simpler version of is_directory for clients that don't need to
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100566/// differentiate between an error and false.
567inline bool is_directory(const Twine &Path) {
568 bool Result;
569 return !is_directory(Path, Result) && Result;
570}
571
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100572/// Does status represent a regular file?
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100573///
574/// @param status A basic_file_status previously returned from status.
575/// @returns status_known(status) && status.type() == file_type::regular_file.
576bool is_regular_file(const basic_file_status &status);
577
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100578/// Is path a regular file?
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100579///
580/// @param path Input path.
581/// @param result Set to true if \a path is a regular file (after following
582/// symlinks), false if it is not. Undefined otherwise.
583/// @returns errc::success if result has been successfully set, otherwise a
584/// platform-specific error_code.
585std::error_code is_regular_file(const Twine &path, bool &result);
586
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100587/// Simpler version of is_regular_file for clients that don't need to
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100588/// differentiate between an error and false.
589inline bool is_regular_file(const Twine &Path) {
590 bool Result;
591 if (is_regular_file(Path, Result))
592 return false;
593 return Result;
594}
595
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100596/// Does status represent a symlink file?
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100597///
598/// @param status A basic_file_status previously returned from status.
599/// @returns status_known(status) && status.type() == file_type::symlink_file.
600bool is_symlink_file(const basic_file_status &status);
601
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100602/// Is path a symlink file?
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100603///
604/// @param path Input path.
605/// @param result Set to true if \a path is a symlink file, false if it is not.
606/// Undefined otherwise.
607/// @returns errc::success if result has been successfully set, otherwise a
608/// platform-specific error_code.
609std::error_code is_symlink_file(const Twine &path, bool &result);
610
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100611/// Simpler version of is_symlink_file for clients that don't need to
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100612/// differentiate between an error and false.
613inline bool is_symlink_file(const Twine &Path) {
614 bool Result;
615 if (is_symlink_file(Path, Result))
616 return false;
617 return Result;
618}
619
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100620/// Does this status represent something that exists but is not a
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100621/// directory or regular file?
622///
623/// @param status A basic_file_status previously returned from status.
624/// @returns exists(s) && !is_regular_file(s) && !is_directory(s)
625bool is_other(const basic_file_status &status);
626
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100627/// Is path something that exists but is not a directory,
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100628/// regular file, or symlink?
629///
630/// @param path Input path.
631/// @param result Set to true if \a path exists, but is not a directory, regular
632/// file, or a symlink, false if it does not. Undefined otherwise.
633/// @returns errc::success if result has been successfully set, otherwise a
634/// platform-specific error_code.
635std::error_code is_other(const Twine &path, bool &result);
636
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100637/// Get file status as if by POSIX stat().
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100638///
639/// @param path Input path.
640/// @param result Set to the file status.
641/// @param follow When true, follows symlinks. Otherwise, the symlink itself is
642/// statted.
643/// @returns errc::success if result has been successfully set, otherwise a
644/// platform-specific error_code.
645std::error_code status(const Twine &path, file_status &result,
646 bool follow = true);
647
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100648/// A version for when a file descriptor is already available.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100649std::error_code status(int FD, file_status &Result);
650
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100651/// Set file permissions.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100652///
653/// @param Path File to set permissions on.
654/// @param Permissions New file permissions.
655/// @returns errc::success if the permissions were successfully set, otherwise
656/// a platform-specific error_code.
657/// @note On Windows, all permissions except *_write are ignored. Using any of
658/// owner_write, group_write, or all_write will make the file writable.
659/// Otherwise, the file will be marked as read-only.
660std::error_code setPermissions(const Twine &Path, perms Permissions);
661
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100662/// Get file permissions.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100663///
664/// @param Path File to get permissions from.
665/// @returns the permissions if they were successfully retrieved, otherwise a
666/// platform-specific error_code.
667/// @note On Windows, if the file does not have the FILE_ATTRIBUTE_READONLY
668/// attribute, all_all will be returned. Otherwise, all_read | all_exe
669/// will be returned.
670ErrorOr<perms> getPermissions(const Twine &Path);
671
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100672/// Get file size.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100673///
674/// @param Path Input path.
675/// @param Result Set to the size of the file in \a Path.
676/// @returns errc::success if result has been successfully set, otherwise a
677/// platform-specific error_code.
678inline std::error_code file_size(const Twine &Path, uint64_t &Result) {
679 file_status Status;
680 std::error_code EC = status(Path, Status);
681 if (EC)
682 return EC;
683 Result = Status.getSize();
684 return std::error_code();
685}
686
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100687/// Set the file modification and access time.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100688///
689/// @returns errc::success if the file times were successfully set, otherwise a
690/// platform-specific error_code or errc::function_not_supported on
691/// platforms where the functionality isn't available.
Andrew Scull0372a572018-11-16 15:47:06 +0000692std::error_code setLastAccessAndModificationTime(int FD, TimePoint<> AccessTime,
693 TimePoint<> ModificationTime);
694
695/// Simpler version that sets both file modification and access time to the same
696/// time.
697inline std::error_code setLastAccessAndModificationTime(int FD,
698 TimePoint<> Time) {
699 return setLastAccessAndModificationTime(FD, Time, Time);
700}
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100701
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100702/// Is status available?
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100703///
704/// @param s Input file status.
705/// @returns True if status() != status_error.
706bool status_known(const basic_file_status &s);
707
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100708/// Is status available?
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100709///
710/// @param path Input path.
711/// @param result Set to true if status() != status_error.
712/// @returns errc::success if result has been successfully set, otherwise a
713/// platform-specific error_code.
714std::error_code status_known(const Twine &path, bool &result);
715
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100716enum CreationDisposition : unsigned {
717 /// CD_CreateAlways - When opening a file:
718 /// * If it already exists, truncate it.
719 /// * If it does not already exist, create a new file.
720 CD_CreateAlways = 0,
721
722 /// CD_CreateNew - When opening a file:
723 /// * If it already exists, fail.
724 /// * If it does not already exist, create a new file.
725 CD_CreateNew = 1,
726
Andrew Scull0372a572018-11-16 15:47:06 +0000727 /// CD_OpenExisting - When opening a file:
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100728 /// * If it already exists, open the file with the offset set to 0.
729 /// * If it does not already exist, fail.
730 CD_OpenExisting = 2,
731
732 /// CD_OpenAlways - When opening a file:
733 /// * If it already exists, open the file with the offset set to 0.
734 /// * If it does not already exist, create a new file.
735 CD_OpenAlways = 3,
736};
737
738enum FileAccess : unsigned {
739 FA_Read = 1,
740 FA_Write = 2,
741};
742
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100743enum OpenFlags : unsigned {
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100744 OF_None = 0,
745 F_None = 0, // For compatibility
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100746
747 /// The file should be opened in text mode on platforms that make this
748 /// distinction.
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100749 OF_Text = 1,
750 F_Text = 1, // For compatibility
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100751
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100752 /// The file should be opened in append mode.
753 OF_Append = 2,
754 F_Append = 2, // For compatibility
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100755
756 /// Delete the file on close. Only makes a difference on windows.
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100757 OF_Delete = 4,
758
759 /// When a child process is launched, this file should remain open in the
760 /// child process.
761 OF_ChildInherit = 8,
762
763 /// Force files Atime to be updated on access. Only makes a difference on windows.
764 OF_UpdateAtime = 16,
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100765};
766
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100767/// Create a uniquely named file.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100768///
769/// Generates a unique path suitable for a temporary file and then opens it as a
770/// file. The name is based on \a model with '%' replaced by a random char in
771/// [0-9a-f]. If \a model is not an absolute path, the temporary file will be
772/// created in the current directory.
773///
774/// Example: clang-%%-%%-%%-%%-%%.s => clang-a0-b1-c2-d3-e4.s
775///
776/// This is an atomic operation. Either the file is created and opened, or the
777/// file system is left untouched.
778///
779/// The intended use is for files that are to be kept, possibly after
780/// renaming them. For example, when running 'clang -c foo.o', the file can
781/// be first created as foo-abc123.o and then renamed.
782///
783/// @param Model Name to base unique path off of.
784/// @param ResultFD Set to the opened file's file descriptor.
785/// @param ResultPath Set to the opened file's absolute path.
786/// @returns errc::success if Result{FD,Path} have been successfully set,
787/// otherwise a platform-specific error_code.
788std::error_code createUniqueFile(const Twine &Model, int &ResultFD,
789 SmallVectorImpl<char> &ResultPath,
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100790 unsigned Mode = all_read | all_write);
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100791
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100792/// Simpler version for clients that don't want an open file. An empty
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100793/// file will still be created.
794std::error_code createUniqueFile(const Twine &Model,
795 SmallVectorImpl<char> &ResultPath,
796 unsigned Mode = all_read | all_write);
797
798/// Represents a temporary file.
799///
800/// The temporary file must be eventually discarded or given a final name and
801/// kept.
802///
803/// The destructor doesn't implicitly discard because there is no way to
804/// properly handle errors in a destructor.
805class TempFile {
806 bool Done = false;
807 TempFile(StringRef Name, int FD);
808
809public:
810 /// This creates a temporary file with createUniqueFile and schedules it for
811 /// deletion with sys::RemoveFileOnSignal.
812 static Expected<TempFile> create(const Twine &Model,
813 unsigned Mode = all_read | all_write);
814 TempFile(TempFile &&Other);
815 TempFile &operator=(TempFile &&Other);
816
817 // Name of the temporary file.
818 std::string TmpName;
819
820 // The open file descriptor.
821 int FD = -1;
822
823 // Keep this with the given name.
824 Error keep(const Twine &Name);
825
826 // Keep this with the temporary name.
827 Error keep();
828
829 // Delete the file.
830 Error discard();
831
832 // This checks that keep or delete was called.
833 ~TempFile();
834};
835
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100836/// Create a file in the system temporary directory.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100837///
838/// The filename is of the form prefix-random_chars.suffix. Since the directory
839/// is not know to the caller, Prefix and Suffix cannot have path separators.
840/// The files are created with mode 0600.
841///
842/// This should be used for things like a temporary .s that is removed after
843/// running the assembler.
844std::error_code createTemporaryFile(const Twine &Prefix, StringRef Suffix,
845 int &ResultFD,
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100846 SmallVectorImpl<char> &ResultPath);
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100847
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100848/// Simpler version for clients that don't want an open file. An empty
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100849/// file will still be created.
850std::error_code createTemporaryFile(const Twine &Prefix, StringRef Suffix,
851 SmallVectorImpl<char> &ResultPath);
852
853std::error_code createUniqueDirectory(const Twine &Prefix,
854 SmallVectorImpl<char> &ResultPath);
855
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100856/// Get a unique name, not currently exisiting in the filesystem. Subject
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100857/// to race conditions, prefer to use createUniqueFile instead.
858///
859/// Similar to createUniqueFile, but instead of creating a file only
860/// checks if it exists. This function is subject to race conditions, if you
861/// want to use the returned name to actually create a file, use
862/// createUniqueFile instead.
863std::error_code getPotentiallyUniqueFileName(const Twine &Model,
864 SmallVectorImpl<char> &ResultPath);
865
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100866/// Get a unique temporary file name, not currently exisiting in the
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100867/// filesystem. Subject to race conditions, prefer to use createTemporaryFile
868/// instead.
869///
870/// Similar to createTemporaryFile, but instead of creating a file only
871/// checks if it exists. This function is subject to race conditions, if you
872/// want to use the returned name to actually create a file, use
873/// createTemporaryFile instead.
874std::error_code
875getPotentiallyUniqueTempFileName(const Twine &Prefix, StringRef Suffix,
876 SmallVectorImpl<char> &ResultPath);
877
878inline OpenFlags operator|(OpenFlags A, OpenFlags B) {
879 return OpenFlags(unsigned(A) | unsigned(B));
880}
881
882inline OpenFlags &operator|=(OpenFlags &A, OpenFlags B) {
883 A = A | B;
884 return A;
885}
886
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100887inline FileAccess operator|(FileAccess A, FileAccess B) {
888 return FileAccess(unsigned(A) | unsigned(B));
889}
Andrew Scull5e1ddfa2018-08-14 10:06:54 +0100890
Andrew Scullcdfcccc2018-10-05 20:58:37 +0100891inline FileAccess &operator|=(FileAccess &A, FileAccess B) {
892 A = A | B;
893 return A;
894}
895
896/// @brief Opens a file with the specified creation disposition, access mode,
897/// and flags and returns a file descriptor.
898///
899/// The caller is responsible for closing the file descriptor once they are
900/// finished with it.
901///
902/// @param Name The path of the file to open, relative or absolute.
903/// @param ResultFD If the file could be opened successfully, its descriptor
904/// is stored in this location. Otherwise, this is set to -1.
905/// @param Disp Value specifying the existing-file behavior.
906/// @param Access Value specifying whether to open the file in read, write, or
907/// read-write mode.
908/// @param Flags Additional flags.
909/// @param Mode The access permissions of the file, represented in octal.
910/// @returns errc::success if \a Name has been opened, otherwise a
911/// platform-specific error_code.
912std::error_code openFile(const Twine &Name, int &ResultFD,
913 CreationDisposition Disp, FileAccess Access,
914 OpenFlags Flags, unsigned Mode = 0666);
915
916/// @brief Opens a file with the specified creation disposition, access mode,
917/// and flags and returns a platform-specific file object.
918///
919/// The caller is responsible for closing the file object once they are
920/// finished with it.
921///
922/// @param Name The path of the file to open, relative or absolute.
923/// @param Disp Value specifying the existing-file behavior.
924/// @param Access Value specifying whether to open the file in read, write, or
925/// read-write mode.
926/// @param Flags Additional flags.
927/// @param Mode The access permissions of the file, represented in octal.
928/// @returns errc::success if \a Name has been opened, otherwise a
929/// platform-specific error_code.
930Expected<file_t> openNativeFile(const Twine &Name, CreationDisposition Disp,
931 FileAccess Access, OpenFlags Flags,
932 unsigned Mode = 0666);
933
934/// @brief Opens the file with the given name in a write-only or read-write
935/// mode, returning its open file descriptor. If the file does not exist, it
936/// is created.
937///
938/// The caller is responsible for closing the file descriptor once they are
939/// finished with it.
940///
941/// @param Name The path of the file to open, relative or absolute.
942/// @param ResultFD If the file could be opened successfully, its descriptor
943/// is stored in this location. Otherwise, this is set to -1.
944/// @param Flags Additional flags used to determine whether the file should be
945/// opened in, for example, read-write or in write-only mode.
946/// @param Mode The access permissions of the file, represented in octal.
947/// @returns errc::success if \a Name has been opened, otherwise a
948/// platform-specific error_code.
949inline std::error_code
950openFileForWrite(const Twine &Name, int &ResultFD,
951 CreationDisposition Disp = CD_CreateAlways,
952 OpenFlags Flags = OF_None, unsigned Mode = 0666) {
953 return openFile(Name, ResultFD, Disp, FA_Write, Flags, Mode);
954}
955
956/// @brief Opens the file with the given name in a write-only or read-write
957/// mode, returning its open file descriptor. If the file does not exist, it
958/// is created.
959///
960/// The caller is responsible for closing the freeing the file once they are
961/// finished with it.
962///
963/// @param Name The path of the file to open, relative or absolute.
964/// @param Flags Additional flags used to determine whether the file should be
965/// opened in, for example, read-write or in write-only mode.
966/// @param Mode The access permissions of the file, represented in octal.
967/// @returns a platform-specific file descriptor if \a Name has been opened,
968/// otherwise an error object.
969inline Expected<file_t> openNativeFileForWrite(const Twine &Name,
970 CreationDisposition Disp,
971 OpenFlags Flags,
972 unsigned Mode = 0666) {
973 return openNativeFile(Name, Disp, FA_Write, Flags, Mode);
974}
975
976/// @brief Opens the file with the given name in a write-only or read-write
977/// mode, returning its open file descriptor. If the file does not exist, it
978/// is created.
979///
980/// The caller is responsible for closing the file descriptor once they are
981/// finished with it.
982///
983/// @param Name The path of the file to open, relative or absolute.
984/// @param ResultFD If the file could be opened successfully, its descriptor
985/// is stored in this location. Otherwise, this is set to -1.
986/// @param Flags Additional flags used to determine whether the file should be
987/// opened in, for example, read-write or in write-only mode.
988/// @param Mode The access permissions of the file, represented in octal.
989/// @returns errc::success if \a Name has been opened, otherwise a
990/// platform-specific error_code.
991inline std::error_code openFileForReadWrite(const Twine &Name, int &ResultFD,
992 CreationDisposition Disp,
993 OpenFlags Flags,
994 unsigned Mode = 0666) {
995 return openFile(Name, ResultFD, Disp, FA_Write | FA_Read, Flags, Mode);
996}
997
998/// @brief Opens the file with the given name in a write-only or read-write
999/// mode, returning its open file descriptor. If the file does not exist, it
1000/// is created.
1001///
1002/// The caller is responsible for closing the freeing the file once they are
1003/// finished with it.
1004///
1005/// @param Name The path of the file to open, relative or absolute.
1006/// @param Flags Additional flags used to determine whether the file should be
1007/// opened in, for example, read-write or in write-only mode.
1008/// @param Mode The access permissions of the file, represented in octal.
1009/// @returns a platform-specific file descriptor if \a Name has been opened,
1010/// otherwise an error object.
1011inline Expected<file_t> openNativeFileForReadWrite(const Twine &Name,
1012 CreationDisposition Disp,
1013 OpenFlags Flags,
1014 unsigned Mode = 0666) {
1015 return openNativeFile(Name, Disp, FA_Write | FA_Read, Flags, Mode);
1016}
1017
1018/// @brief Opens the file with the given name in a read-only mode, returning
1019/// its open file descriptor.
1020///
1021/// The caller is responsible for closing the file descriptor once they are
1022/// finished with it.
1023///
1024/// @param Name The path of the file to open, relative or absolute.
1025/// @param ResultFD If the file could be opened successfully, its descriptor
1026/// is stored in this location. Otherwise, this is set to -1.
1027/// @param RealPath If nonnull, extra work is done to determine the real path
1028/// of the opened file, and that path is stored in this
1029/// location.
1030/// @returns errc::success if \a Name has been opened, otherwise a
1031/// platform-specific error_code.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +01001032std::error_code openFileForRead(const Twine &Name, int &ResultFD,
Andrew Scullcdfcccc2018-10-05 20:58:37 +01001033 OpenFlags Flags = OF_None,
Andrew Scull5e1ddfa2018-08-14 10:06:54 +01001034 SmallVectorImpl<char> *RealPath = nullptr);
1035
Andrew Scullcdfcccc2018-10-05 20:58:37 +01001036/// @brief Opens the file with the given name in a read-only mode, returning
1037/// its open file descriptor.
1038///
1039/// The caller is responsible for closing the freeing the file once they are
1040/// finished with it.
1041///
1042/// @param Name The path of the file to open, relative or absolute.
1043/// @param RealPath If nonnull, extra work is done to determine the real path
1044/// of the opened file, and that path is stored in this
1045/// location.
1046/// @returns a platform-specific file descriptor if \a Name has been opened,
1047/// otherwise an error object.
1048Expected<file_t>
1049openNativeFileForRead(const Twine &Name, OpenFlags Flags = OF_None,
1050 SmallVectorImpl<char> *RealPath = nullptr);
1051
1052/// @brief Close the file object. This should be used instead of ::close for
1053/// portability.
1054///
1055/// @param F On input, this is the file to close. On output, the file is
1056/// set to kInvalidFile.
1057void closeFile(file_t &F);
1058
Andrew Scull5e1ddfa2018-08-14 10:06:54 +01001059std::error_code getUniqueID(const Twine Path, UniqueID &Result);
1060
Andrew Scullcdfcccc2018-10-05 20:58:37 +01001061/// Get disk space usage information.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +01001062///
1063/// Note: Users must be careful about "Time Of Check, Time Of Use" kind of bug.
1064/// Note: Windows reports results according to the quota allocated to the user.
1065///
1066/// @param Path Input path.
1067/// @returns a space_info structure filled with the capacity, free, and
1068/// available space on the device \a Path is on. A platform specific error_code
1069/// is returned on error.
1070ErrorOr<space_info> disk_space(const Twine &Path);
1071
1072/// This class represents a memory mapped file. It is based on
1073/// boost::iostreams::mapped_file.
1074class mapped_file_region {
1075public:
1076 enum mapmode {
1077 readonly, ///< May only access map via const_data as read only.
1078 readwrite, ///< May access map via data and modify it. Written to path.
1079 priv ///< May modify via data, but changes are lost on destruction.
1080 };
1081
1082private:
1083 /// Platform-specific mapping state.
1084 size_t Size;
1085 void *Mapping;
Andrew Scullcdfcccc2018-10-05 20:58:37 +01001086#ifdef _WIN32
1087 void *FileHandle;
1088#endif
Andrew Scull5e1ddfa2018-08-14 10:06:54 +01001089 mapmode Mode;
1090
1091 std::error_code init(int FD, uint64_t Offset, mapmode Mode);
1092
1093public:
1094 mapped_file_region() = delete;
1095 mapped_file_region(mapped_file_region&) = delete;
1096 mapped_file_region &operator =(mapped_file_region&) = delete;
1097
1098 /// \param fd An open file descriptor to map. mapped_file_region takes
1099 /// ownership if closefd is true. It must have been opended in the correct
1100 /// mode.
1101 mapped_file_region(int fd, mapmode mode, size_t length, uint64_t offset,
1102 std::error_code &ec);
1103
1104 ~mapped_file_region();
1105
1106 size_t size() const;
1107 char *data() const;
1108
1109 /// Get a const view of the data. Modifying this memory has undefined
1110 /// behavior.
1111 const char *const_data() const;
1112
1113 /// \returns The minimum alignment offset must be.
1114 static int alignment();
1115};
1116
1117/// Return the path to the main executable, given the value of argv[0] from
1118/// program startup and the address of main itself. In extremis, this function
1119/// may fail and return an empty path.
1120std::string getMainExecutable(const char *argv0, void *MainExecAddr);
1121
1122/// @}
1123/// @name Iterators
1124/// @{
1125
Andrew Scull0372a572018-11-16 15:47:06 +00001126/// directory_entry - A single entry in a directory.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +01001127class directory_entry {
Andrew Scull0372a572018-11-16 15:47:06 +00001128 // FIXME: different platforms make different information available "for free"
1129 // when traversing a directory. The design of this class wraps most of the
1130 // information in basic_file_status, so on platforms where we can't populate
1131 // that whole structure, callers end up paying for a stat().
1132 // std::filesystem::directory_entry may be a better model.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +01001133 std::string Path;
Andrew Scull0372a572018-11-16 15:47:06 +00001134 file_type Type; // Most platforms can provide this.
1135 bool FollowSymlinks; // Affects the behavior of status().
1136 basic_file_status Status; // If available.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +01001137
1138public:
Andrew Scull0372a572018-11-16 15:47:06 +00001139 explicit directory_entry(const Twine &Path, bool FollowSymlinks = true,
1140 file_type Type = file_type::type_unknown,
1141 basic_file_status Status = basic_file_status())
1142 : Path(Path.str()), Type(Type), FollowSymlinks(FollowSymlinks),
1143 Status(Status) {}
Andrew Scull5e1ddfa2018-08-14 10:06:54 +01001144
1145 directory_entry() = default;
1146
Andrew Scull0372a572018-11-16 15:47:06 +00001147 void replace_filename(const Twine &Filename, file_type Type,
1148 basic_file_status Status = basic_file_status());
Andrew Scull5e1ddfa2018-08-14 10:06:54 +01001149
1150 const std::string &path() const { return Path; }
Andrew Scull0372a572018-11-16 15:47:06 +00001151 // Get basic information about entry file (a subset of fs::status()).
1152 // On most platforms this is a stat() call.
1153 // On windows the information was already retrieved from the directory.
Andrew Scull5e1ddfa2018-08-14 10:06:54 +01001154 ErrorOr<basic_file_status> status() const;
Andrew Scull0372a572018-11-16 15:47:06 +00001155 // Get the type of this file.
1156 // On most platforms (Linux/Mac/Windows/BSD), this was already retrieved.
1157 // On some platforms (e.g. Solaris) this is a stat() call.
1158 file_type type() const {
1159 if (Type != file_type::type_unknown)
1160 return Type;
1161 auto S = status();
1162 return S ? S->type() : file_type::type_unknown;
1163 }
Andrew Scull5e1ddfa2018-08-14 10:06:54 +01001164
Andrew Scull0372a572018-11-16 15:47:06 +00001165 bool operator==(const directory_entry& RHS) const { return Path == RHS.Path; }
1166 bool operator!=(const directory_entry& RHS) const { return !(*this == RHS); }
1167 bool operator< (const directory_entry& RHS) const;
1168 bool operator<=(const directory_entry& RHS) const;
1169 bool operator> (const directory_entry& RHS) const;
1170 bool operator>=(const directory_entry& RHS) const;
Andrew Scull5e1ddfa2018-08-14 10:06:54 +01001171};
1172
1173namespace detail {
1174
1175 struct DirIterState;
1176
1177 std::error_code directory_iterator_construct(DirIterState &, StringRef, bool);
1178 std::error_code directory_iterator_increment(DirIterState &);
1179 std::error_code directory_iterator_destruct(DirIterState &);
1180
1181 /// Keeps state for the directory_iterator.
1182 struct DirIterState {
1183 ~DirIterState() {
1184 directory_iterator_destruct(*this);
1185 }
1186
1187 intptr_t IterationHandle = 0;
1188 directory_entry CurrentEntry;
1189 };
1190
1191} // end namespace detail
1192
1193/// directory_iterator - Iterates through the entries in path. There is no
1194/// operator++ because we need an error_code. If it's really needed we can make
1195/// it call report_fatal_error on error.
1196class directory_iterator {
1197 std::shared_ptr<detail::DirIterState> State;
1198 bool FollowSymlinks = true;
1199
1200public:
1201 explicit directory_iterator(const Twine &path, std::error_code &ec,
1202 bool follow_symlinks = true)
1203 : FollowSymlinks(follow_symlinks) {
1204 State = std::make_shared<detail::DirIterState>();
1205 SmallString<128> path_storage;
1206 ec = detail::directory_iterator_construct(
1207 *State, path.toStringRef(path_storage), FollowSymlinks);
1208 }
1209
1210 explicit directory_iterator(const directory_entry &de, std::error_code &ec,
1211 bool follow_symlinks = true)
1212 : FollowSymlinks(follow_symlinks) {
1213 State = std::make_shared<detail::DirIterState>();
Andrew Scullcdfcccc2018-10-05 20:58:37 +01001214 ec = detail::directory_iterator_construct(
1215 *State, de.path(), FollowSymlinks);
Andrew Scull5e1ddfa2018-08-14 10:06:54 +01001216 }
1217
1218 /// Construct end iterator.
1219 directory_iterator() = default;
1220
1221 // No operator++ because we need error_code.
1222 directory_iterator &increment(std::error_code &ec) {
1223 ec = directory_iterator_increment(*State);
1224 return *this;
1225 }
1226
1227 const directory_entry &operator*() const { return State->CurrentEntry; }
1228 const directory_entry *operator->() const { return &State->CurrentEntry; }
1229
1230 bool operator==(const directory_iterator &RHS) const {
1231 if (State == RHS.State)
1232 return true;
1233 if (!RHS.State)
1234 return State->CurrentEntry == directory_entry();
1235 if (!State)
1236 return RHS.State->CurrentEntry == directory_entry();
1237 return State->CurrentEntry == RHS.State->CurrentEntry;
1238 }
1239
1240 bool operator!=(const directory_iterator &RHS) const {
1241 return !(*this == RHS);
1242 }
Andrew Scull5e1ddfa2018-08-14 10:06:54 +01001243};
1244
1245namespace detail {
1246
1247 /// Keeps state for the recursive_directory_iterator.
1248 struct RecDirIterState {
1249 std::stack<directory_iterator, std::vector<directory_iterator>> Stack;
1250 uint16_t Level = 0;
1251 bool HasNoPushRequest = false;
1252 };
1253
1254} // end namespace detail
1255
1256/// recursive_directory_iterator - Same as directory_iterator except for it
1257/// recurses down into child directories.
1258class recursive_directory_iterator {
1259 std::shared_ptr<detail::RecDirIterState> State;
1260 bool Follow;
1261
1262public:
1263 recursive_directory_iterator() = default;
1264 explicit recursive_directory_iterator(const Twine &path, std::error_code &ec,
1265 bool follow_symlinks = true)
1266 : State(std::make_shared<detail::RecDirIterState>()),
1267 Follow(follow_symlinks) {
1268 State->Stack.push(directory_iterator(path, ec, Follow));
1269 if (State->Stack.top() == directory_iterator())
1270 State.reset();
1271 }
1272
1273 // No operator++ because we need error_code.
1274 recursive_directory_iterator &increment(std::error_code &ec) {
1275 const directory_iterator end_itr = {};
1276
1277 if (State->HasNoPushRequest)
1278 State->HasNoPushRequest = false;
1279 else {
Andrew Scull0372a572018-11-16 15:47:06 +00001280 file_type type = State->Stack.top()->type();
1281 if (type == file_type::symlink_file && Follow) {
1282 // Resolve the symlink: is it a directory to recurse into?
1283 ErrorOr<basic_file_status> status = State->Stack.top()->status();
1284 if (status)
1285 type = status->type();
1286 // Otherwise broken symlink, and we'll continue.
1287 }
1288 if (type == file_type::directory_file) {
Andrew Scull5e1ddfa2018-08-14 10:06:54 +01001289 State->Stack.push(directory_iterator(*State->Stack.top(), ec, Follow));
Andrew Scull5e1ddfa2018-08-14 10:06:54 +01001290 if (State->Stack.top() != end_itr) {
1291 ++State->Level;
1292 return *this;
1293 }
1294 State->Stack.pop();
1295 }
1296 }
1297
1298 while (!State->Stack.empty()
1299 && State->Stack.top().increment(ec) == end_itr) {
1300 State->Stack.pop();
1301 --State->Level;
1302 }
1303
1304 // Check if we are done. If so, create an end iterator.
1305 if (State->Stack.empty())
1306 State.reset();
1307
1308 return *this;
1309 }
1310
1311 const directory_entry &operator*() const { return *State->Stack.top(); }
1312 const directory_entry *operator->() const { return &*State->Stack.top(); }
1313
1314 // observers
1315 /// Gets the current level. Starting path is at level 0.
1316 int level() const { return State->Level; }
1317
1318 /// Returns true if no_push has been called for this directory_entry.
1319 bool no_push_request() const { return State->HasNoPushRequest; }
1320
1321 // modifiers
1322 /// Goes up one level if Level > 0.
1323 void pop() {
1324 assert(State && "Cannot pop an end iterator!");
1325 assert(State->Level > 0 && "Cannot pop an iterator with level < 1");
1326
1327 const directory_iterator end_itr = {};
1328 std::error_code ec;
1329 do {
1330 if (ec)
1331 report_fatal_error("Error incrementing directory iterator.");
1332 State->Stack.pop();
1333 --State->Level;
1334 } while (!State->Stack.empty()
1335 && State->Stack.top().increment(ec) == end_itr);
1336
1337 // Check if we are done. If so, create an end iterator.
1338 if (State->Stack.empty())
1339 State.reset();
1340 }
1341
1342 /// Does not go down into the current directory_entry.
1343 void no_push() { State->HasNoPushRequest = true; }
1344
1345 bool operator==(const recursive_directory_iterator &RHS) const {
1346 return State == RHS.State;
1347 }
1348
1349 bool operator!=(const recursive_directory_iterator &RHS) const {
1350 return !(*this == RHS);
1351 }
Andrew Scull5e1ddfa2018-08-14 10:06:54 +01001352};
1353
1354/// @}
1355
1356} // end namespace fs
1357} // end namespace sys
1358} // end namespace llvm
1359
1360#endif // LLVM_SUPPORT_FILESYSTEM_H