1 //===- llvm/Support/PathV2.h - Path Operating System Concept ----*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 // This file declares the llvm::sys::{path,fs} namespaces. It is designed after
11 // TR2/boost filesystem (v3), but modified to remove exception handling and the
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
25 //===----------------------------------------------------------------------===//
27 #ifndef LLVM_SYSTEM_PATHV2_H
28 #define LLVM_SYSTEM_PATHV2_H
30 #include "llvm/ADT/SmallString.h"
31 #include "llvm/ADT/Twine.h"
32 #include "llvm/Support/DataTypes.h"
33 #include "llvm/Support/system_error.h"
47 /// @name Lexical Component Iterator
50 /// @brief Path iterator.
52 /// This is a bidirectional iterator that iterates over the individual
53 /// components in \a path. The forward traversal order is as follows:
54 /// * The root-name element, if present.
55 /// * The root-directory element, if present.
56 /// * Each successive filename element, if present.
57 /// * Dot, if one or more trailing non-root slash characters are present.
58 /// The backwards traversal order is the reverse of forward traversal.
60 /// Iteration examples. Each component is separated by ',':
64 /// /foo/bar => /,foo,bar
66 /// C:\foo\bar => C:,/,foo,bar
68 class const_iterator {
69 StringRef Path; //< The entire path.
70 StringRef Component; //< The current component. Not necessarily in Path.
71 size_t Position; //< The iterators current position within Path.
73 // An end iterator has Position = Path.size() + 1.
74 friend const_iterator begin(const StringRef &path);
75 friend const_iterator end(const StringRef &path);
78 typedef const StringRef value_type;
79 typedef ptrdiff_t difference_type;
80 typedef value_type &reference;
81 typedef value_type *pointer;
82 typedef std::bidirectional_iterator_tag iterator_category;
84 reference operator*() const { return Component; }
85 pointer operator->() const { return &Component; }
86 const_iterator &operator++(); // preincrement
87 const_iterator &operator++(int); // postincrement
88 const_iterator &operator--(); // predecrement
89 const_iterator &operator--(int); // postdecrement
90 bool operator==(const const_iterator &RHS) const;
91 bool operator!=(const const_iterator &RHS) const;
93 /// @brief Difference in bytes between this and RHS.
94 ptrdiff_t operator-(const const_iterator &RHS) const;
97 typedef std::reverse_iterator<const_iterator> reverse_iterator;
99 /// @brief Get begin iterator over \a path.
100 /// @param path Input path.
101 /// @returns Iterator initialized with the first component of \a path.
102 const_iterator begin(const StringRef &path);
104 /// @brief Get end iterator over \a path.
105 /// @param path Input path.
106 /// @returns Iterator initialized to the end of \a path.
107 const_iterator end(const StringRef &path);
109 /// @brief Get reverse begin iterator over \a path.
110 /// @param path Input path.
111 /// @returns Iterator initialized with the first reverse component of \a path.
112 inline reverse_iterator rbegin(const StringRef &path) {
113 return reverse_iterator(end(path));
116 /// @brief Get reverse end iterator over \a path.
117 /// @param path Input path.
118 /// @returns Iterator initialized to the reverse end of \a path.
119 inline reverse_iterator rend(const StringRef &path) {
120 return reverse_iterator(begin(path));
124 /// @name Lexical Modifiers
127 /// @brief Make \a path an absolute path.
129 /// Makes \a path absolute using the current directory if it is not already. An
130 /// empty \a path will result in the current directory.
132 /// /absolute/path => /absolute/path
133 /// relative/../path => <current-directory>/path
135 /// @param path A path that is modified to be an absolute path.
136 /// @returns errc::success if \a path has been made absolute, otherwise a
137 /// platform specific error_code.
138 error_code make_absolute(SmallVectorImpl<char> &path);
140 /// @brief Remove the last component from \a path if it exists.
142 /// directory/filename.cpp => directory/
143 /// directory/ => directory
145 /// @param path A path that is modified to not have a file component.
146 /// @returns errc::success if \a path's file name has been removed (or there was
147 /// not one to begin with), otherwise a platform specific error_code.
148 error_code remove_filename(SmallVectorImpl<char> &path);
150 /// @brief Replace the file extension of \a path with \a extension.
152 /// ./filename.cpp => ./filename.extension
153 /// ./filename => ./filename.extension
154 /// ./ => ? TODO: decide what semantics this has.
156 /// @param path A path that has its extension replaced with \a extension.
157 /// @param extension The extension to be added. It may be empty. It may also
158 /// optionally start with a '.', if it does not, one will be
160 /// @returns errc::success if \a path's extension has been replaced, otherwise a
161 /// platform specific error_code.
162 error_code replace_extension(SmallVectorImpl<char> &path,
163 const Twine &extension);
165 /// @brief Append to path.
167 /// /foo + bar/f => /foo/bar/f
168 /// /foo/ + bar/f => /foo/bar/f
169 /// foo + bar/f => foo/bar/f
171 /// @param path Set to \a path + \a component.
172 /// @param component The component to be appended to \a path.
173 /// @returns errc::success if \a component has been appended to \a path,
174 /// otherwise a platform specific error_code.
175 error_code append(SmallVectorImpl<char> &path, const Twine &a,
178 const Twine &d = "");
180 /// @brief Append to path.
182 /// /foo + [bar,f] => /foo/bar/f
183 /// /foo/ + [bar,f] => /foo/bar/f
184 /// foo + [bar,f] => foo/bar/f
186 /// @param path Set to \a path + [\a begin, \a end).
187 /// @param begin Start of components to append.
188 /// @param end One past the end of components to append.
189 /// @returns errc::success if [\a begin, \a end) has been appended to \a path,
190 /// otherwise a platform specific error_code.
191 error_code append(SmallVectorImpl<char> &path,
192 const_iterator begin, const_iterator end);
195 /// @name Transforms (or some other better name)
198 /// Convert path to the native form. This is used to give paths to users and
199 /// operating system calls in the platform's normal way. For example, on Windows
200 /// all '/' are converted to '\'.
202 /// @param path A path that is transformed to native format.
203 /// @param result Holds the result of the transformation.
204 /// @returns errc::success if \a path has been transformed and stored in result,
205 /// otherwise a platform specific error_code.
206 error_code native(const Twine &path, SmallVectorImpl<char> &result);
209 /// @name Lexical Observers
212 /// @brief Get the current path.
214 /// @param result Holds the current path on return.
215 /// @results errc::success if the current path has been stored in result,
216 /// otherwise a platform specific error_code.
217 error_code current_path(SmallVectorImpl<char> &result);
219 // The following are purely lexical.
221 /// @brief Is the current path valid?
223 /// @param path Input path.
224 /// @param result Set to true if the path is valid, false if it is not.
225 /// @results errc::success if result has been successfully set, otherwise a
226 /// platform specific error_code.
227 error_code is_valid(const Twine &path, bool &result);
229 /// @brief Get root name.
231 /// //net/hello => //net
232 /// c:/hello => c: (on Windows, on other platforms nothing)
233 /// /hello => <empty>
235 /// @param path Input path.
236 /// @param result Set to the root name of \a path if it has one, otherwise "".
237 /// @results errc::success if result has been successfully set, otherwise a
238 /// platform specific error_code.
239 error_code root_name(const StringRef &path, StringRef &result);
241 /// @brief Get root directory.
245 /// d/file.txt => <empty>
247 /// @param path Input path.
248 /// @param result Set to the root directory of \a path if it has one, otherwise
250 /// @results errc::success if result has been successfully set, otherwise a
251 /// platform specific error_code.
252 error_code root_directory(const StringRef &path, StringRef &result);
254 /// @brief Get root path.
256 /// Equivalent to root_name + root_directory.
258 /// @param path Input path.
259 /// @param result Set to the root path of \a path if it has one, otherwise "".
260 /// @results errc::success if result has been successfully set, otherwise a
261 /// platform specific error_code.
262 error_code root_path(const StringRef &path, StringRef &result);
264 /// @brief Get relative path.
266 /// C:\hello\world => hello\world
267 /// foo/bar => foo/bar
268 /// /foo/bar => foo/bar
270 /// @param path Input path.
271 /// @param result Set to the path starting after root_path if one exists,
273 /// @results errc::success if result has been successfully set, otherwise a
274 /// platform specific error_code.
275 error_code relative_path(const StringRef &path, StringRef &result);
277 /// @brief Get parent path.
281 /// foo/../bar => foo/..
283 /// @param path Input path.
284 /// @param result Set to the parent path of \a path if one exists, otherwise "".
285 /// @results errc::success if result has been successfully set, otherwise a
286 /// platform specific error_code.
287 error_code parent_path(const StringRef &path, StringRef &result);
289 /// @brief Get filename.
291 /// /foo.txt => foo.txt
296 /// @param path Input path.
297 /// @param result Set to the filename part of \a path. This is defined as the
298 /// last component of \a path.
299 /// @results errc::success if result has been successfully set, otherwise a
300 /// platform specific error_code.
301 error_code filename(const StringRef &path, StringRef &result);
305 /// If filename contains a dot but not solely one or two dots, result is the
306 /// substring of filename ending at (but not including) the last dot. Otherwise
309 /// /foo/bar.txt => bar
311 /// /foo/.txt => <empty>
315 /// @param path Input path.
316 /// @param result Set to the stem of \a path.
317 /// @results errc::success if result has been successfully set, otherwise a
318 /// platform specific error_code.
319 error_code stem(const StringRef &path, StringRef &result);
321 /// @brief Get extension.
323 /// If filename contains a dot but not solely one or two dots, result is the
324 /// substring of filename starting at (and including) the last dot, and ending
325 /// at the end of \a path. Otherwise "".
327 /// /foo/bar.txt => .txt
328 /// /foo/bar => <empty>
329 /// /foo/.txt => .txt
331 /// @param path Input path.
332 /// @param result Set to the extension of \a path.
333 /// @results errc::success if result has been successfully set, otherwise a
334 /// platform specific error_code.
335 error_code extension(const StringRef &path, StringRef &result);
337 /// @brief Has root name?
341 /// @param path Input path.
342 /// @param result Set to true if the path has a root name, false otherwise.
343 /// @results errc::success if result has been successfully set, otherwise a
344 /// platform specific error_code.
345 error_code has_root_name(const Twine &path, bool &result);
347 /// @brief Has root directory?
349 /// root_directory != ""
351 /// @param path Input path.
352 /// @param result Set to true if the path has a root directory, false otherwise.
353 /// @results errc::success if result has been successfully set, otherwise a
354 /// platform specific error_code.
355 error_code has_root_directory(const Twine &path, bool &result);
357 /// @brief Has root path?
361 /// @param path Input path.
362 /// @param result Set to true if the path has a root path, false otherwise.
363 /// @results errc::success if result has been successfully set, otherwise a
364 /// platform specific error_code.
365 error_code has_root_path(const Twine &path, bool &result);
367 /// @brief Has relative path?
369 /// relative_path != ""
371 /// @param path Input path.
372 /// @param result Set to true if the path has a relative path, false otherwise.
373 /// @results errc::success if result has been successfully set, otherwise a
374 /// platform specific error_code.
375 error_code has_relative_path(const Twine &path, bool &result);
377 /// @brief Has parent path?
379 /// parent_path != ""
381 /// @param path Input path.
382 /// @param result Set to true if the path has a parent path, false otherwise.
383 /// @results errc::success if result has been successfully set, otherwise a
384 /// platform specific error_code.
385 error_code has_parent_path(const Twine &path, bool &result);
387 /// @brief Has filename?
391 /// @param path Input path.
392 /// @param result Set to true if the path has a filename, false otherwise.
393 /// @results errc::success if result has been successfully set, otherwise a
394 /// platform specific error_code.
395 error_code has_filename(const Twine &path, bool &result);
401 /// @param path Input path.
402 /// @param result Set to true if the path has a stem, false otherwise.
403 /// @results errc::success if result has been successfully set, otherwise a
404 /// platform specific error_code.
405 error_code has_stem(const Twine &path, bool &result);
407 /// @brief Has extension?
411 /// @param path Input path.
412 /// @param result Set to true if the path has a extension, false otherwise.
413 /// @results errc::success if result has been successfully set, otherwise a
414 /// platform specific error_code.
415 error_code has_extension(const Twine &path, bool &result);
417 /// @brief Is path absolute?
419 /// @param path Input path.
420 /// @param result Set to true if the path is absolute, false if it is not.
421 /// @results errc::success if result has been successfully set, otherwise a
422 /// platform specific error_code.
423 error_code is_absolute(const Twine &path, bool &result);
425 /// @brief Is path relative?
427 /// @param path Input path.
428 /// @param result Set to true if the path is relative, false if it is not.
429 /// @results errc::success if result has been successfully set, otherwise a
430 /// platform specific error_code.
431 error_code is_relative(const Twine &path, bool &result);
432 // end purely lexical.
434 } // end namespace path
438 /// file_type - An "enum class" enumeration for the file system's view of the
454 file_type(_ v) : v_(v) {}
455 explicit file_type(int v) : v_(_(v)) {}
456 operator int() const {return v_;}
462 /// copy_option - An "enum class" enumeration of copy semantics for copy
470 copy_option(_ v) : v_(v) {}
471 explicit copy_option(int v) : v_(_(v)) {}
472 operator int() const {return v_;}
478 /// space_info - Self explanatory.
485 /// file_status - Represents the result of a call to stat and friends. It has
486 /// a platform specific member to store the result.
489 // implementation defined status field.
491 explicit file_status(file_type v=file_type::status_error);
493 file_type type() const;
494 void type(file_type v);
498 /// @name Physical Operators
501 /// @brief Copy the file at \a from to the path \a to.
503 /// @param from The path to copy the file from.
504 /// @param to The path to copy the file to.
505 /// @param copt Behavior if \a to already exists.
506 /// @returns errc::success if the file has been successfully copied.
507 /// errc::file_exists if \a to already exists and \a copt ==
508 /// copy_option::fail_if_exists. Otherwise a platform specific
510 error_code copy_file(const Twine &from, const Twine &to,
511 copy_option copt = copy_option::fail_if_exists);
513 /// @brief Create all the non-existent directories in path.
515 /// @param path Directories to create.
516 /// @param existed Set to true if \a path already existed, false otherwise.
517 /// @returns errc::success if is_directory(path) and existed have been set,
518 /// otherwise a platform specific error_code.
519 error_code create_directories(const Twine &path, bool &existed);
521 /// @brief Create the directory in path.
523 /// @param path Directory to create.
524 /// @param existed Set to true if \a path already existed, false otherwise.
525 /// @returns errc::success if is_directory(path) and existed have been set,
526 /// otherwise a platform specific error_code.
527 error_code create_directory(const Twine &path, bool &existed);
529 /// @brief Create a hard link from \a from to \a to.
531 /// @param to The path to hard link to.
532 /// @param from The path to hard link from. This is created.
533 /// @returns errc::success if exists(to) && exists(from) && equivalent(to, from)
534 /// , otherwise a platform specific error_code.
535 error_code create_hard_link(const Twine &to, const Twine &from);
537 /// @brief Create a symbolic link from \a from to \a to.
539 /// @param to The path to symbolically link to.
540 /// @param from The path to symbolically link from. This is created.
541 /// @returns errc::success if exists(to) && exists(from) && is_symlink(from),
542 /// otherwise a platform specific error_code.
543 error_code create_symlink(const Twine &to, const Twine &from);
545 /// @brief Remove path. Equivalent to POSIX remove().
547 /// @param path Input path.
548 /// @param existed Set to true if \a path existed, false if it did not.
549 /// undefined otherwise.
550 /// @results errc::success if path has been removed and existed has been
551 /// successfully set, otherwise a platform specific error_code.
552 error_code remove(const Twine &path, bool &existed);
554 /// @brief Recursively remove all files below \a path, then \a path. Files are
555 /// removed as if by POSIX remove().
557 /// @param path Input path.
558 /// @param num_removed Number of files removed.
559 /// @results errc::success if path has been removed and num_removed has been
560 /// successfully set, otherwise a platform specific error_code.
561 error_code remove_all(const Twine &path, uint32_t &num_removed);
563 /// @brief Rename \a from to \a to. Files are renamed as if by POSIX rename().
565 /// @param from The path to rename from.
566 /// @param to The path to rename to. This is created.
567 error_code rename(const Twine &from, const Twine &to);
569 /// @brief Resize path to size. File is resized as if by POSIX truncate().
571 /// @param path Input path.
572 /// @param size Size to resize to.
573 /// @returns errc::success if \a path has been resized to \a size, otherwise a
574 /// platform specific error_code.
575 error_code resize_file(const Twine &path, uint64_t size);
577 /// @brief Make file readable.
579 /// @param path Input path.
580 /// @param value If true, make readable, else, make unreadable.
581 /// @results errc::success if readability has been successfully set, otherwise a
582 /// platform specific error_code.
583 error_code set_read(const Twine &path, bool value);
585 /// @brief Make file writeable.
587 /// @param path Input path.
588 /// @param value If true, make writeable, else, make unwriteable.
589 /// @results errc::success if writeability has been successfully set, otherwise
590 /// a platform specific error_code.
591 error_code set_write(const Twine &path, bool value);
593 /// @brief Make file executable.
595 /// @param path Input path.
596 /// @param value If true, make executable, else, make unexecutable.
597 /// @results errc::success if executability has been successfully set, otherwise
598 /// a platform specific error_code.
599 error_code set_execute(const Twine &path, bool value);
602 /// @name Physical Observers
605 /// @brief Does file exist?
607 /// @param status A file_status previously returned from stat.
608 /// @param result Set to true if the file represented by status exists, false if
609 /// it does not. Undefined otherwise.
610 /// @results errc::success if result has been successfully set, otherwise a
611 /// platform specific error_code.
612 error_code exists(file_status status, bool &result);
614 /// @brief Does file exist?
616 /// @param path Input path.
617 /// @param result Set to true if the file represented by status exists, false if
618 /// it does not. Undefined otherwise.
619 /// @results errc::success if result has been successfully set, otherwise a
620 /// platform specific error_code.
621 error_code exists(const Twine &path, bool &result);
623 /// @brief Do paths represent the same thing?
625 /// @param A Input path A.
626 /// @param B Input path B.
627 /// @param result Set to true if stat(A) and stat(B) have the same device and
628 /// inode (or equivalent).
629 /// @results errc::success if result has been successfully set, otherwise a
630 /// platform specific error_code.
631 error_code equivalent(const Twine &A, const Twine &B, bool &result);
633 /// @brief Get file size.
635 /// @param path Input path.
636 /// @param result Set to the size of the file in \a path.
637 /// @returns errc::success if result has been successfully set, otherwise a
638 /// platform specific error_code.
639 error_code file_size(const Twine &path, uint64_t &result);
641 /// @brief Does status represent a directory?
643 /// @param status A file_status previously returned from stat.
644 /// @param result Set to true if the file represented by status is a directory,
645 /// false if it is not. Undefined otherwise.
646 /// @results errc::success if result has been successfully set, otherwise a
647 /// platform specific error_code.
648 error_code is_directory(file_status status, bool &result);
650 /// @brief Is path a directory?
652 /// @param path Input path.
653 /// @param result Set to true if \a path is a directory, false if it is not.
654 /// Undefined otherwise.
655 /// @results errc::success if result has been successfully set, otherwise a
656 /// platform specific error_code.
657 error_code is_directory(const Twine &path, bool &result);
659 /// @brief Is path an empty file?
661 /// @param path Input path.
662 /// @param result Set to true if \a path is a an empty file, false if it is not.
663 /// Undefined otherwise.
664 /// @results errc::success if result has been successfully set, otherwise a
665 /// platform specific error_code.
666 error_code is_empty(const Twine &path, bool &result);
668 /// @brief Does status represent a regular file?
670 /// @param status A file_status previously returned from stat.
671 /// @param result Set to true if the file represented by status is a regular
672 /// file, false if it is not. Undefined otherwise.
673 /// @results errc::success if result has been successfully set, otherwise a
674 /// platform specific error_code.
675 error_code is_regular_file(file_status status, bool &result);
677 /// @brief Is path a regular file?
679 /// @param path Input path.
680 /// @param result Set to true if \a path is a regular file, false if it is not.
681 /// Undefined otherwise.
682 /// @results errc::success if result has been successfully set, otherwise a
683 /// platform specific error_code.
684 error_code is_regular_file(const Twine &path, bool &result);
686 /// @brief Does status represent something that exists but is not a directory,
687 /// regular file, or symlink?
689 /// @param status A file_status previously returned from stat.
690 /// @param result Set to true if the file represented by status exists, but is
691 /// not a directory, regular file, or a symlink, false if it does
692 /// not. Undefined otherwise.
693 /// @results errc::success if result has been successfully set, otherwise a
694 /// platform specific error_code.
695 error_code is_other(file_status status, bool &result);
697 /// @brief Is path something that exists but is not a directory,
698 /// regular file, or symlink?
700 /// @param path Input path.
701 /// @param result Set to true if \a path exists, but is not a directory, regular
702 /// file, or a symlink, false if it does not. Undefined otherwise.
703 /// @results errc::success if result has been successfully set, otherwise a
704 /// platform specific error_code.
705 error_code is_other(const Twine &path, bool &result);
707 /// @brief Does status represent a symlink?
709 /// @param status A file_status previously returned from stat.
710 /// @param result Set to true if the file represented by status is a symlink,
711 /// false if it is not. Undefined otherwise.
712 /// @results errc::success if result has been successfully set, otherwise a
713 /// platform specific error_code.
714 error_code is_symlink(file_status status, bool &result);
716 /// @brief Is path a symlink?
718 /// @param path Input path.
719 /// @param result Set to true if \a path is a symlink, false if it is not.
720 /// Undefined otherwise.
721 /// @results errc::success if result has been successfully set, otherwise a
722 /// platform specific error_code.
723 error_code is_symlink(const Twine &path, bool &result);
725 /// @brief Get last write time without changing it.
727 /// @param path Input path.
728 /// @param result Set to the last write time (UNIX time) of \a path if it
730 /// @results errc::success if result has been successfully set, otherwise a
731 /// platform specific error_code.
732 error_code last_write_time(const Twine &path, std::time_t &result);
734 /// @brief Set last write time.
736 /// @param path Input path.
737 /// @param value Time to set (UNIX time) \a path's last write time to.
738 /// @results errc::success if result has been successfully set, otherwise a
739 /// platform specific error_code.
740 error_code set_last_write_time(const Twine &path, std::time_t value);
742 /// @brief Read a symlink's value.
744 /// @param path Input path.
745 /// @param result Set to the value of the symbolic link \a path.
746 /// @results errc::success if result has been successfully set, otherwise a
747 /// platform specific error_code.
748 error_code read_symlink(const Twine &path, SmallVectorImpl<char> &result);
750 /// @brief Get disk space usage information.
752 /// @param path Input path.
753 /// @param result Set to the capacity, free, and available space on the device
755 /// @results errc::success if result has been successfully set, otherwise a
756 /// platform specific error_code.
757 error_code disk_space(const Twine &path, space_info &result);
759 /// @brief Get file status as if by POSIX stat().
761 /// @param path Input path.
762 /// @param result Set to the file status.
763 /// @results errc::success if result has been successfully set, otherwise a
764 /// platform specific error_code.
765 error_code status(const Twine &path, file_status &result);
767 /// @brief Is status available?
769 /// @param path Input path.
770 /// @param result Set to true if status() != status_error.
771 /// @results errc::success if result has been successfully set, otherwise a
772 /// platform specific error_code.
773 error_code status_known(const Twine &path, bool &result);
775 /// @brief Get file status as if by POSIX lstat().
777 /// Does not resolve symlinks.
779 /// @param path Input path.
780 /// @param result Set to the file status.
781 /// @results errc::success if result has been successfully set, otherwise a
782 /// platform specific error_code.
783 error_code symlink_status(const Twine &path, file_status &result);
785 /// @brief Get the temporary directory.
787 /// @param result Set to the temporary directory.
788 /// @results errc::success if result has been successfully set, otherwise a
789 /// platform specific error_code.
791 error_code temp_directory_path(SmallVectorImpl<char> &result);
793 /// @brief Generate a unique path and open it as a file.
795 /// Generates a unique path suitable for a temporary file and then opens it as a
796 /// file. The name is based on \a model with '%' replaced by a random char in
799 /// This is an atomic operation. Either the file is created and opened, or the
800 /// file system is left untouched.
802 /// clang-%%-%%-%%-%%-%%.s => <current-directory>/clang-a0-b1-c2-d3-e4.s
804 /// @param model Name to base unique path off of.
805 /// @param result Set to the opened file.
806 /// @results errc::success if result has been successfully set, otherwise a
807 /// platform specific error_code.
808 /// @see temp_directory_path
809 error_code unique_file(const Twine &model, void* i_have_not_decided_the_ty_yet);
811 /// @brief Canonicalize path.
813 /// Sets result to the file system's idea of what path is. The result is always
814 /// absolute and has the same capitalization as the file system.
816 /// @param path Input path.
817 /// @param result Set to the canonicalized version of \a path.
818 /// @results errc::success if result has been successfully set, otherwise a
819 /// platform specific error_code.
820 error_code canonicalize(const Twine &path, SmallVectorImpl<char> &result);
822 /// @brief Are \a path's first bytes \a magic?
824 /// @param path Input path.
825 /// @param magic Byte sequence to compare \a path's first len(magic) bytes to.
826 /// @results errc::success if result has been successfully set, otherwise a
827 /// platform specific error_code.
828 error_code has_magic(const Twine &path, const Twine &magic);
830 /// @brief Get \a path's first \a len bytes.
832 /// @param path Input path.
833 /// @param len Number of magic bytes to get.
834 /// @param result Set to the first \a len bytes in the file pointed to by
836 /// @results errc::success if result has been successfully set, otherwise a
837 /// platform specific error_code.
838 error_code get_magic(const Twine &path, uint32_t len,
839 SmallVectorImpl<char> &result);
841 /// @brief Is file bitcode?
843 /// @param path Input path.
844 /// @param result Set to true if \a path is a bitcode file, false if it is not,
845 /// undefined otherwise.
846 /// @results errc::success if result has been successfully set, otherwise a
847 /// platform specific error_code.
848 error_code is_bitcode(const Twine &path, bool &result);
850 /// @brief Is file a dynamic library?
852 /// @param path Input path.
853 /// @param result Set to true if \a path is a dynamic library, false if it is
854 /// not, undefined otherwise.
855 /// @results errc::success if result has been successfully set, otherwise a
856 /// platform specific error_code.
857 error_code is_dynamic_library(const Twine &path, bool &result);
859 /// @brief Is an object file?
861 /// @param path Input path.
862 /// @param result Set to true if \a path is an object file, false if it is not,
863 /// undefined otherwise.
864 /// @results errc::success if result has been successfully set, otherwise a
865 /// platform specific error_code.
866 error_code is_object_file(const Twine &path, bool &result);
868 /// @brief Can file be read?
870 /// @param path Input path.
871 /// @param result Set to true if \a path is readable, false it it is not,
872 /// undefined otherwise.
873 /// @results errc::success if result has been successfully set, otherwise a
874 /// platform specific error_code.
875 error_code can_read(const Twine &path, bool &result);
877 /// @brief Can file be written?
879 /// @param path Input path.
880 /// @param result Set to true if \a path is writeable, false it it is not,
881 /// undefined otherwise.
882 /// @results errc::success if result has been successfully set, otherwise a
883 /// platform specific error_code.
884 error_code can_write(const Twine &path, bool &result);
886 /// @brief Can file be executed?
888 /// @param path Input path.
889 /// @param result Set to true if \a path is executable, false it it is not,
890 /// undefined otherwise.
891 /// @results errc::success if result has been successfully set, otherwise a
892 /// platform specific error_code.
893 error_code can_execute(const Twine &path, bool &result);
895 /// @brief Get library paths the system linker uses.
897 /// @param result Set to the list of system library paths.
898 /// @results errc::success if result has been successfully set, otherwise a
899 /// platform specific error_code.
900 error_code GetSystemLibraryPaths(SmallVectorImpl<std::string> &result);
902 /// @brief Get bitcode library paths the system linker uses
903 /// + LLVM_LIB_SEARCH_PATH + LLVM_LIBDIR.
905 /// @param result Set to the list of bitcode library paths.
906 /// @results errc::success if result has been successfully set, otherwise a
907 /// platform specific error_code.
908 error_code GetBitcodeLibraryPaths(SmallVectorImpl<std::string> &result);
910 /// @brief Find a library.
912 /// Find the path to a library using its short name. Use the system
913 /// dependent library paths to locate the library.
915 /// c => /usr/lib/libc.so
917 /// @param short_name Library name one would give to the system linker.
918 /// @param result Set to the absolute path \a short_name represents.
919 /// @results errc::success if result has been successfully set, otherwise a
920 /// platform specific error_code.
921 error_code FindLibrary(const Twine &short_name, SmallVectorImpl<char> &result);
923 /// @brief Get absolute path of main executable.
925 /// @param argv0 The program name as it was spelled on the command line.
926 /// @param MainAddr Address of some symbol in the executable (not in a library).
927 /// @param result Set to the absolute path of the current executable.
928 /// @results errc::success if result has been successfully set, otherwise a
929 /// platform specific error_code.
930 error_code GetMainExecutable(const char *argv0, void *MainAddr,
931 SmallVectorImpl<char> &result);
937 /// directory_entry - A single entry in a directory. Caches the status either
938 /// from the result of the iteration syscall, or the first time status or
939 /// symlink_status is called.
940 class directory_entry {
942 mutable file_status Status;
943 mutable file_status SymlinkStatus;
946 explicit directory_entry(const Twine &path, file_status st = file_status(),
947 file_status symlink_st = file_status());
949 void assign(const Twine &path, file_status st = file_status(),
950 file_status symlink_st = file_status());
951 void replace_filename(const Twine &filename, file_status st = file_status(),
952 file_status symlink_st = file_status());
954 const SmallVectorImpl<char> &path() const;
955 error_code status(file_status &result) const;
956 error_code symlink_status(file_status &result) const;
958 bool operator==(const directory_entry& rhs) const;
959 bool operator!=(const directory_entry& rhs) const;
960 bool operator< (const directory_entry& rhs) const;
961 bool operator<=(const directory_entry& rhs) const;
962 bool operator> (const directory_entry& rhs) const;
963 bool operator>=(const directory_entry& rhs) const;
966 /// directory_iterator - Iterates through the entries in path. There is no
967 /// operator++ because we need an error_code. If it's really needed we can make
968 /// it call report_fatal_error on error.
969 class directory_iterator {
970 // implementation directory iterator status
973 explicit directory_iterator(const Twine &path, error_code &ec);
974 // No operator++ because we need error_code.
975 directory_iterator &increment(error_code &ec);
977 const directory_entry &operator*() const;
978 const directory_entry *operator->() const;
980 // Other members as required by
981 // C++ Std, 24.1.1 Input iterators [input.iterators]
984 /// recursive_directory_iterator - Same as directory_iterator except for it
985 /// recurses down into child directories.
986 class recursive_directory_iterator {
988 bool HasNoPushRequest;
989 // implementation directory iterator status
992 explicit recursive_directory_iterator(const Twine &path, error_code &ec);
993 // No operator++ because we need error_code.
994 directory_iterator &increment(error_code &ec);
996 const directory_entry &operator*() const;
997 const directory_entry *operator->() const;
1000 /// Gets the current level. path is at level 0.
1002 /// Returns true if no_push has been called for this directory_entry.
1003 bool no_push_request() const;
1006 /// Goes up one level if Level > 0.
1008 /// Does not go down into the current directory_entry.
1011 // Other members as required by
1012 // C++ Std, 24.1.1 Input iterators [input.iterators]
1017 } // end namespace fs
1018 } // end namespace sys
1019 } // end namespace llvm