1 //===- llvm/Support/FileSystem.h - File System OS Concept -------*- C++ -*-===// 2 // 3 // The LLVM Compiler Infrastructure 4 // 5 // This file is distributed under the University of Illinois Open Source 6 // License. See LICENSE.TXT for details. 7 // 8 //===----------------------------------------------------------------------===// 9 // 10 // This file declares the llvm::sys::fs namespace. It is designed after 11 // TR2/boost filesystem (v3), but modified to remove exception handling and the 12 // path class. 13 // 14 // All functions return an error_code and their actual work via the last out 15 // argument. The out argument is defined if and only if errc::success is 16 // returned. A function may return any error code in the generic or system 17 // category. However, they shall be equivalent to any error conditions listed 18 // in each functions respective documentation if the condition applies. [ note: 19 // this does not guarantee that error_code will be in the set of explicitly 20 // listed codes, but it does guarantee that if any of the explicitly listed 21 // errors occur, the correct error_code will be used ]. All functions may 22 // return errc::not_enough_memory if there is not enough memory to complete the 23 // operation. 24 // 25 //===----------------------------------------------------------------------===// 26 27 #ifndef LLVM_SUPPORT_FILE_SYSTEM_H 28 #define LLVM_SUPPORT_FILE_SYSTEM_H 29 30 #include "llvm/ADT/SmallString.h" 31 #include "llvm/ADT/Twine.h" 32 #include "llvm/Support/DataTypes.h" 33 #include "llvm/Support/PathV1.h" 34 #include "llvm/Support/system_error.h" 35 #include <ctime> 36 #include <iterator> 37 #include <string> 38 39 namespace llvm { 40 namespace sys { 41 namespace fs { 42 43 /// file_type - An "enum class" enumeration for the file system's view of the 44 /// type. 45 struct file_type { 46 enum _ { 47 status_error, 48 file_not_found, 49 regular_file, 50 directory_file, 51 symlink_file, 52 block_file, 53 character_file, 54 fifo_file, 55 socket_file, 56 type_unknown 57 }; 58 59 file_type(_ v) : v_(v) {} 60 explicit file_type(int v) : v_(_(v)) {} 61 operator int() const {return v_;} 62 63 private: 64 int v_; 65 }; 66 67 /// copy_option - An "enum class" enumeration of copy semantics for copy 68 /// operations. 69 struct copy_option { 70 enum _ { 71 fail_if_exists, 72 overwrite_if_exists 73 }; 74 75 copy_option(_ v) : v_(v) {} 76 explicit copy_option(int v) : v_(_(v)) {} 77 operator int() const {return v_;} 78 79 private: 80 int v_; 81 }; 82 83 /// space_info - Self explanatory. 84 struct space_info { 85 uint64_t capacity; 86 uint64_t free; 87 uint64_t available; 88 }; 89 90 /// file_status - Represents the result of a call to stat and friends. It has 91 /// a platform specific member to store the result. 92 class file_status 93 { 94 // implementation defined status field. 95 file_type Type; 96 public: 97 explicit file_status(file_type v=file_type::status_error) 98 : Type(v) {} 99 100 file_type type() const { return Type; } 101 void type(file_type v) { Type = v; } 102 }; 103 104 /// @} 105 /// @name Physical Operators 106 /// @{ 107 108 /// @brief Make \a path an absolute path. 109 /// 110 /// Makes \a path absolute using the current directory if it is not already. An 111 /// empty \a path will result in the current directory. 112 /// 113 /// /absolute/path => /absolute/path 114 /// relative/../path => <current-directory>/relative/../path 115 /// 116 /// @param path A path that is modified to be an absolute path. 117 /// @returns errc::success if \a path has been made absolute, otherwise a 118 /// platform specific error_code. 119 error_code make_absolute(SmallVectorImpl<char> &path); 120 121 /// @brief Copy the file at \a from to the path \a to. 122 /// 123 /// @param from The path to copy the file from. 124 /// @param to The path to copy the file to. 125 /// @param copt Behavior if \a to already exists. 126 /// @returns errc::success if the file has been successfully copied. 127 /// errc::file_exists if \a to already exists and \a copt == 128 /// copy_option::fail_if_exists. Otherwise a platform specific 129 /// error_code. 130 error_code copy_file(const Twine &from, const Twine &to, 131 copy_option copt = copy_option::fail_if_exists); 132 133 /// @brief Create all the non-existent directories in path. 134 /// 135 /// @param path Directories to create. 136 /// @param existed Set to true if \a path already existed, false otherwise. 137 /// @returns errc::success if is_directory(path) and existed have been set, 138 /// otherwise a platform specific error_code. 139 error_code create_directories(const Twine &path, bool &existed); 140 141 /// @brief Create the directory in path. 142 /// 143 /// @param path Directory to create. 144 /// @param existed Set to true if \a path already existed, false otherwise. 145 /// @returns errc::success if is_directory(path) and existed have been set, 146 /// otherwise a platform specific error_code. 147 error_code create_directory(const Twine &path, bool &existed); 148 149 /// @brief Create a hard link from \a from to \a to. 150 /// 151 /// @param to The path to hard link to. 152 /// @param from The path to hard link from. This is created. 153 /// @returns errc::success if exists(to) && exists(from) && equivalent(to, from) 154 /// , otherwise a platform specific error_code. 155 error_code create_hard_link(const Twine &to, const Twine &from); 156 157 /// @brief Create a symbolic link from \a from to \a to. 158 /// 159 /// @param to The path to symbolically link to. 160 /// @param from The path to symbolically link from. This is created. 161 /// @returns errc::success if exists(to) && exists(from) && is_symlink(from), 162 /// otherwise a platform specific error_code. 163 error_code create_symlink(const Twine &to, const Twine &from); 164 165 /// @brief Get the current path. 166 /// 167 /// @param result Holds the current path on return. 168 /// @results errc::success if the current path has been stored in result, 169 /// otherwise a platform specific error_code. 170 error_code current_path(SmallVectorImpl<char> &result); 171 172 /// @brief Remove path. Equivalent to POSIX remove(). 173 /// 174 /// @param path Input path. 175 /// @param existed Set to true if \a path existed, false if it did not. 176 /// undefined otherwise. 177 /// @results errc::success if path has been removed and existed has been 178 /// successfully set, otherwise a platform specific error_code. 179 error_code remove(const Twine &path, bool &existed); 180 181 /// @brief Recursively remove all files below \a path, then \a path. Files are 182 /// removed as if by POSIX remove(). 183 /// 184 /// @param path Input path. 185 /// @param num_removed Number of files removed. 186 /// @results errc::success if path has been removed and num_removed has been 187 /// successfully set, otherwise a platform specific error_code. 188 error_code remove_all(const Twine &path, uint32_t &num_removed); 189 190 /// @brief Rename \a from to \a to. Files are renamed as if by POSIX rename(). 191 /// 192 /// @param from The path to rename from. 193 /// @param to The path to rename to. This is created. 194 error_code rename(const Twine &from, const Twine &to); 195 196 /// @brief Resize path to size. File is resized as if by POSIX truncate(). 197 /// 198 /// @param path Input path. 199 /// @param size Size to resize to. 200 /// @returns errc::success if \a path has been resized to \a size, otherwise a 201 /// platform specific error_code. 202 error_code resize_file(const Twine &path, uint64_t size); 203 204 /// @} 205 /// @name Physical Observers 206 /// @{ 207 208 /// @brief Does file exist? 209 /// 210 /// @param status A file_status previously returned from stat. 211 /// @results True if the file represented by status exists, false if it does 212 /// not. 213 bool exists(file_status status); 214 215 /// @brief Does file exist? 216 /// 217 /// @param path Input path. 218 /// @param result Set to true if the file represented by status exists, false if 219 /// it does not. Undefined otherwise. 220 /// @results errc::success if result has been successfully set, otherwise a 221 /// platform specific error_code. 222 error_code exists(const Twine &path, bool &result); 223 224 /// @brief Simpler version of exists for clients that don't need to 225 /// differentiate between an error and false. 226 inline bool exists(const Twine &path) { 227 bool result; 228 return !exists(path, result) && result; 229 } 230 231 /// @brief Do file_status's represent the same thing? 232 /// 233 /// @param A Input file_status. 234 /// @param B Input file_status. 235 /// 236 /// assert(status_known(A) || status_known(B)); 237 /// 238 /// @results True if A and B both represent the same file system entity, false 239 /// otherwise. 240 bool equivalent(file_status A, file_status B); 241 242 /// @brief Do paths represent the same thing? 243 /// 244 /// @param A Input path A. 245 /// @param B Input path B. 246 /// @param result Set to true if stat(A) and stat(B) have the same device and 247 /// inode (or equivalent). 248 /// @results errc::success if result has been successfully set, otherwise a 249 /// platform specific error_code. 250 error_code equivalent(const Twine &A, const Twine &B, bool &result); 251 252 /// @brief Get file size. 253 /// 254 /// @param path Input path. 255 /// @param result Set to the size of the file in \a path. 256 /// @returns errc::success if result has been successfully set, otherwise a 257 /// platform specific error_code. 258 error_code file_size(const Twine &path, uint64_t &result); 259 260 /// @brief Does status represent a directory? 261 /// 262 /// @param status A file_status previously returned from status. 263 /// @results status.type() == file_type::directory_file. 264 bool is_directory(file_status status); 265 266 /// @brief Is path a directory? 267 /// 268 /// @param path Input path. 269 /// @param result Set to true if \a path is a directory, false if it is not. 270 /// Undefined otherwise. 271 /// @results errc::success if result has been successfully set, otherwise a 272 /// platform specific error_code. 273 error_code is_directory(const Twine &path, bool &result); 274 275 /// @brief Does status represent a regular file? 276 /// 277 /// @param status A file_status previously returned from status. 278 /// @results status_known(status) && status.type() == file_type::regular_file. 279 bool is_regular_file(file_status status); 280 281 /// @brief Is path a regular file? 282 /// 283 /// @param path Input path. 284 /// @param result Set to true if \a path is a regular file, false if it is not. 285 /// Undefined otherwise. 286 /// @results errc::success if result has been successfully set, otherwise a 287 /// platform specific error_code. 288 error_code is_regular_file(const Twine &path, bool &result); 289 290 /// @brief Does this status represent something that exists but is not a 291 /// directory, regular file, or symlink? 292 /// 293 /// @param status A file_status previously returned from status. 294 /// @results exists(s) && !is_regular_file(s) && !is_directory(s) && 295 /// !is_symlink(s) 296 bool is_other(file_status status); 297 298 /// @brief Is path something that exists but is not a directory, 299 /// regular file, or symlink? 300 /// 301 /// @param path Input path. 302 /// @param result Set to true if \a path exists, but is not a directory, regular 303 /// file, or a symlink, false if it does not. Undefined otherwise. 304 /// @results errc::success if result has been successfully set, otherwise a 305 /// platform specific error_code. 306 error_code is_other(const Twine &path, bool &result); 307 308 /// @brief Does status represent a symlink? 309 /// 310 /// @param status A file_status previously returned from stat. 311 /// @param result status.type() == symlink_file. 312 bool is_symlink(file_status status); 313 314 /// @brief Is path a symlink? 315 /// 316 /// @param path Input path. 317 /// @param result Set to true if \a path is a symlink, false if it is not. 318 /// Undefined otherwise. 319 /// @results errc::success if result has been successfully set, otherwise a 320 /// platform specific error_code. 321 error_code is_symlink(const Twine &path, bool &result); 322 323 /// @brief Get file status as if by POSIX stat(). 324 /// 325 /// @param path Input path. 326 /// @param result Set to the file status. 327 /// @results errc::success if result has been successfully set, otherwise a 328 /// platform specific error_code. 329 error_code status(const Twine &path, file_status &result); 330 331 /// @brief Is status available? 332 /// 333 /// @param path Input path. 334 /// @results True if status() != status_error. 335 bool status_known(file_status s); 336 337 /// @brief Is status available? 338 /// 339 /// @param path Input path. 340 /// @param result Set to true if status() != status_error. 341 /// @results errc::success if result has been successfully set, otherwise a 342 /// platform specific error_code. 343 error_code status_known(const Twine &path, bool &result); 344 345 /// @brief Generate a unique path and open it as a file. 346 /// 347 /// Generates a unique path suitable for a temporary file and then opens it as a 348 /// file. The name is based on \a model with '%' replaced by a random char in 349 /// [0-9a-f]. If \a model is not an absolute path, a suitable temporary 350 /// directory will be prepended. 351 /// 352 /// This is an atomic operation. Either the file is created and opened, or the 353 /// file system is left untouched. 354 /// 355 /// clang-%%-%%-%%-%%-%%.s => /tmp/clang-a0-b1-c2-d3-e4.s 356 /// 357 /// @param model Name to base unique path off of. 358 /// @param result_fs Set to the opened file's file descriptor. 359 /// @param result_path Set to the opened file's absolute path. 360 /// @param makeAbsolute If true and @model is not an absolute path, a temp 361 /// directory will be prepended. 362 /// @results errc::success if result_{fd,path} have been successfully set, 363 /// otherwise a platform specific error_code. 364 error_code unique_file(const Twine &model, int &result_fd, 365 SmallVectorImpl<char> &result_path, 366 bool makeAbsolute = true); 367 368 /// @brief Canonicalize path. 369 /// 370 /// Sets result to the file system's idea of what path is. The result is always 371 /// absolute and has the same capitalization as the file system. 372 /// 373 /// @param path Input path. 374 /// @param result Set to the canonicalized version of \a path. 375 /// @results errc::success if result has been successfully set, otherwise a 376 /// platform specific error_code. 377 error_code canonicalize(const Twine &path, SmallVectorImpl<char> &result); 378 379 /// @brief Are \a path's first bytes \a magic? 380 /// 381 /// @param path Input path. 382 /// @param magic Byte sequence to compare \a path's first len(magic) bytes to. 383 /// @results errc::success if result has been successfully set, otherwise a 384 /// platform specific error_code. 385 error_code has_magic(const Twine &path, const Twine &magic, bool &result); 386 387 /// @brief Get \a path's first \a len bytes. 388 /// 389 /// @param path Input path. 390 /// @param len Number of magic bytes to get. 391 /// @param result Set to the first \a len bytes in the file pointed to by 392 /// \a path. Or the entire file if file_size(path) < len, in which 393 /// case result.size() returns the size of the file. 394 /// @results errc::success if result has been successfully set, 395 /// errc::value_too_large if len is larger then the file pointed to by 396 /// \a path, otherwise a platform specific error_code. 397 error_code get_magic(const Twine &path, uint32_t len, 398 SmallVectorImpl<char> &result); 399 400 /// @brief Get and identify \a path's type based on its content. 401 /// 402 /// @param path Input path. 403 /// @param result Set to the type of file, or LLVMFileType::Unknown_FileType. 404 /// @results errc::success if result has been successfully set, otherwise a 405 /// platform specific error_code. 406 error_code identify_magic(const Twine &path, LLVMFileType &result); 407 408 /// @brief Get library paths the system linker uses. 409 /// 410 /// @param result Set to the list of system library paths. 411 /// @results errc::success if result has been successfully set, otherwise a 412 /// platform specific error_code. 413 error_code GetSystemLibraryPaths(SmallVectorImpl<std::string> &result); 414 415 /// @brief Get bitcode library paths the system linker uses 416 /// + LLVM_LIB_SEARCH_PATH + LLVM_LIBDIR. 417 /// 418 /// @param result Set to the list of bitcode library paths. 419 /// @results errc::success if result has been successfully set, otherwise a 420 /// platform specific error_code. 421 error_code GetBitcodeLibraryPaths(SmallVectorImpl<std::string> &result); 422 423 /// @brief Find a library. 424 /// 425 /// Find the path to a library using its short name. Use the system 426 /// dependent library paths to locate the library. 427 /// 428 /// c => /usr/lib/libc.so 429 /// 430 /// @param short_name Library name one would give to the system linker. 431 /// @param result Set to the absolute path \a short_name represents. 432 /// @results errc::success if result has been successfully set, otherwise a 433 /// platform specific error_code. 434 error_code FindLibrary(const Twine &short_name, SmallVectorImpl<char> &result); 435 436 /// @brief Get absolute path of main executable. 437 /// 438 /// @param argv0 The program name as it was spelled on the command line. 439 /// @param MainAddr Address of some symbol in the executable (not in a library). 440 /// @param result Set to the absolute path of the current executable. 441 /// @results errc::success if result has been successfully set, otherwise a 442 /// platform specific error_code. 443 error_code GetMainExecutable(const char *argv0, void *MainAddr, 444 SmallVectorImpl<char> &result); 445 446 /// @} 447 /// @name Iterators 448 /// @{ 449 450 /// directory_entry - A single entry in a directory. Caches the status either 451 /// from the result of the iteration syscall, or the first time status is 452 /// called. 453 class directory_entry { 454 std::string Path; 455 mutable file_status Status; 456 457 public: 458 explicit directory_entry(const Twine &path, file_status st = file_status()) 459 : Path(path.str()) 460 , Status(st) {} 461 462 directory_entry() {} 463 464 void assign(const Twine &path, file_status st = file_status()) { 465 Path = path.str(); 466 Status = st; 467 } 468 469 void replace_filename(const Twine &filename, file_status st = file_status()); 470 471 const std::string &path() const { return Path; } 472 error_code status(file_status &result) const; 473 474 bool operator==(const directory_entry& rhs) const { return Path == rhs.Path; } 475 bool operator!=(const directory_entry& rhs) const { return !(*this == rhs); } 476 bool operator< (const directory_entry& rhs) const; 477 bool operator<=(const directory_entry& rhs) const; 478 bool operator> (const directory_entry& rhs) const; 479 bool operator>=(const directory_entry& rhs) const; 480 }; 481 482 /// directory_iterator - Iterates through the entries in path. There is no 483 /// operator++ because we need an error_code. If it's really needed we can make 484 /// it call report_fatal_error on error. 485 class directory_iterator { 486 intptr_t IterationHandle; 487 directory_entry CurrentEntry; 488 489 // Platform implementations implement these functions to handle iteration. 490 friend error_code directory_iterator_construct(directory_iterator &it, 491 StringRef path); 492 friend error_code directory_iterator_increment(directory_iterator &it); 493 friend error_code directory_iterator_destruct(directory_iterator &it); 494 495 public: 496 explicit directory_iterator(const Twine &path, error_code &ec) 497 : IterationHandle(0) { 498 SmallString<128> path_storage; 499 ec = directory_iterator_construct(*this, path.toStringRef(path_storage)); 500 } 501 502 /// Construct end iterator. 503 directory_iterator() : IterationHandle(0) {} 504 505 ~directory_iterator() { 506 directory_iterator_destruct(*this); 507 } 508 509 // No operator++ because we need error_code. 510 directory_iterator &increment(error_code &ec) { 511 ec = directory_iterator_increment(*this); 512 return *this; 513 } 514 515 const directory_entry &operator*() const { return CurrentEntry; } 516 const directory_entry *operator->() const { return &CurrentEntry; } 517 518 bool operator!=(const directory_iterator &RHS) const { 519 return CurrentEntry != RHS.CurrentEntry; 520 } 521 // Other members as required by 522 // C++ Std, 24.1.1 Input iterators [input.iterators] 523 }; 524 525 /// recursive_directory_iterator - Same as directory_iterator except for it 526 /// recurses down into child directories. 527 class recursive_directory_iterator { 528 uint16_t Level; 529 bool HasNoPushRequest; 530 // implementation directory iterator status 531 532 public: 533 explicit recursive_directory_iterator(const Twine &path, error_code &ec); 534 // No operator++ because we need error_code. 535 directory_iterator &increment(error_code &ec); 536 537 const directory_entry &operator*() const; 538 const directory_entry *operator->() const; 539 540 // observers 541 /// Gets the current level. path is at level 0. 542 int level() const; 543 /// Returns true if no_push has been called for this directory_entry. 544 bool no_push_request() const; 545 546 // modifiers 547 /// Goes up one level if Level > 0. 548 void pop(); 549 /// Does not go down into the current directory_entry. 550 void no_push(); 551 552 // Other members as required by 553 // C++ Std, 24.1.1 Input iterators [input.iterators] 554 }; 555 556 /// @} 557 558 } // end namespace fs 559 } // end namespace sys 560 } // end namespace llvm 561 562 #endif 563