Merge System into Support.
[oota-llvm.git] / include / llvm / Support / PathV2.h
1 //===- llvm/System/PathV2.h - Path Operating System 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::path 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 #include "llvm/ADT/SmallString.h"
28 #include "llvm/Support/DataTypes.h"
29 #include "llvm/Support/system_error.h"
30 #include <ctime>
31 #include <iterator>
32 #include <string>
33
34 namespace llvm {
35
36 // Forward decls.
37 class StringRef;
38 class Twine;
39
40 namespace sys {
41 namespace path {
42
43 /// @name Lexical Component Iterator
44 /// @{
45
46 /// @brief Path iterator.
47 ///
48 /// This is a bidirectional iterator that iterates over the individual
49 /// components in \a path. The forward traversal order is as follows:
50 /// * The root-name element, if present.
51 /// * The root-directory element, if present.
52 /// * Each successive filename element, if present.
53 /// * Dot, if one or more trailing non-root slash characters are present.
54 /// The backwards traversal order is the reverse of forward traversal.
55 ///
56 /// Iteration examples. Each component is separated by ',':
57 /// /          => /
58 /// /foo       => /,foo
59 /// foo/       => foo,.
60 /// /foo/bar   => /,foo,bar
61 /// ../        => ..,.
62 /// C:\foo\bar => C:,/,foo,bar
63 ///
64 class const_iterator {
65   StringRef Path;      //< The entire path.
66   StringRef Component; //< The current component.
67
68 public:
69   typedef const StringRef value_type;
70   typedef value_type &reference;
71   typedef value_type *pointer;
72   typedef std::bidirectional_iterator_tag iterator_category;
73   reference operator*() const;
74   pointer   operator->() const;
75   const_iterator &operator++();    // preincrement
76   const_iterator &operator++(int); // postincrement
77   const_iterator &operator--();    // predecrement
78   const_iterator &operator--(int); // postdecrement
79   bool operator==(const const_iterator &RHS) const;
80   bool operator!=(const const_iterator &RHS) const;
81
82   const_iterator(); //< Default construct end iterator.
83   const_iterator(const StringRef &path);
84 };
85
86 /// @}
87 /// @name Lexical Modifiers
88 /// @{
89
90 /// @brief Make \a path an absolute path.
91 ///
92 /// Makes \a path absolute using the current directory if it is not already. An
93 /// empty \a path will result in the current directory.
94 ///
95 /// /absolute/path   => /absolute/path
96 /// relative/../path => <current-directory>/path
97 ///
98 /// @param path A path that is modified to be an absolute path.
99 /// @returns errc::success if \a path has been made absolute, otherwise a
100 ///          platform specific error_code.
101 error_code make_absolute(SmallVectorImpl<char> &path);
102
103 /// @brief Remove the last component from \a path if it exists.
104 ///
105 /// directory/filename.cpp => directory/
106 /// directory/             => directory/
107 ///
108 /// @param path A path that is modified to not have a file component.
109 /// @returns errc::success if \a path's file name has been removed (or there was
110 ///          not one to begin with), otherwise a platform specific error_code.
111 error_code remove_filename(SmallVectorImpl<char> &path);
112
113 /// @brief Replace the file extension of \a path with \a extension.
114 ///
115 /// ./filename.cpp => ./filename.extension
116 /// ./filename     => ./filename.extension
117 /// ./             => ? TODO: decide what semantics this has.
118 ///
119 /// @param path A path that has its extension replaced with \a extension.
120 /// @param extension The extension to be added. It may be empty. It may also
121 ///                  optionally start with a '.', if it does not, one will be
122 ///                  prepended.
123 /// @returns errc::success if \a path's extension has been replaced, otherwise a
124 ///          platform specific error_code.
125 error_code replace_extension(SmallVectorImpl<char> &path,
126                              const Twine &extension);
127
128 /// @brief Append to path.
129 ///
130 /// /foo  + bar/f => /foo/bar/f
131 /// /foo/ + bar/f => /foo/bar/f
132 /// foo   + bar/f => foo/bar/f
133 ///
134 /// @param path Set to \a path + \a component.
135 /// @param component The component to be appended to \a path.
136 /// @returns errc::success if \a component has been appended to \a path,
137 ///          otherwise a platform specific error_code.
138 error_code append(SmallVectorImpl<char> &path, const Twine &component);
139
140 /// @brief Append to path.
141 ///
142 /// /foo  + [bar,f] => /foo/bar/f
143 /// /foo/ + [bar,f] => /foo/bar/f
144 /// foo   + [bar,f] => foo/bar/f
145 ///
146 /// @param path Set to \a path + [\a begin, \a end).
147 /// @param begin Start of components to append.
148 /// @param end One past the end of components to append.
149 /// @returns errc::success if [\a begin, \a end) has been appended to \a path,
150 ///          otherwise a platform specific error_code.
151 error_code append(SmallVectorImpl<char> &path,
152                   const_iterator begin, const_iterator end);
153
154 /// @}
155 /// @name Transforms (or some other better name)
156 /// @{
157
158 /// Convert path to the native form. This is used to give paths to users and
159 /// operating system calls in the platform's normal way. For example, on Windows
160 /// all '/' are converted to '\'.
161 ///
162 /// @param path A path that is transformed to native format.
163 /// @param result Holds the result of the transformation.
164 /// @returns errc::success if \a path has been transformed and stored in result,
165 ///          otherwise a platform specific error_code.
166 error_code native(const Twine &path, SmallVectorImpl<char> &result);
167
168 /// @}
169 /// @name Lexical Observers
170 /// @{
171
172 /// @brief Get the current path.
173 ///
174 /// @param result Holds the current path on return.
175 /// @results errc::success if the current path has been stored in result,
176 ///          otherwise a platform specific error_code.
177 error_code current_path(SmallVectorImpl<char> &result);
178
179 // The following are purely lexical.
180
181 /// @brief Is the current path valid?
182 ///
183 /// @param path Input path.
184 /// @param result Set to true if the path is valid, false if it is not.
185 /// @results errc::success if result has been successfully set, otherwise a
186 ///          platform specific error_code.
187 error_code is_valid(const Twine &path, bool &result);
188
189 /// @brief Get root name.
190 ///
191 /// //net/hello => //net
192 /// c:/hello    => c: (on Windows, on other platforms nothing)
193 /// /hello      => <empty>
194 ///
195 /// @param path Input path.
196 /// @param result Set to the root name of \a path if it has one, otherwise "".
197 /// @results errc::success if result has been successfully set, otherwise a
198 ///          platform specific error_code.
199 error_code root_name(const StringRef &path, StringRef &result);
200
201 /// @brief Get root directory.
202 ///
203 /// /goo/hello => /
204 /// c:/hello   => /
205 /// d/file.txt => <empty>
206 ///
207 /// @param path Input path.
208 /// @param result Set to the root directory of \a path if it has one, otherwise
209 ///               "".
210 /// @results errc::success if result has been successfully set, otherwise a
211 ///          platform specific error_code.
212 error_code root_directory(const StringRef &path, StringRef &result);
213
214 /// @brief Get root path.
215 ///
216 /// Equivalent to root_name + root_directory.
217 ///
218 /// @param path Input path.
219 /// @param result Set to the root path of \a path if it has one, otherwise "".
220 /// @results errc::success if result has been successfully set, otherwise a
221 ///          platform specific error_code.
222 error_code root_path(const StringRef &path, StringRef &result);
223
224 /// @brief Get relative path.
225 ///
226 /// C:\hello\world => hello\world
227 /// foo/bar        => foo/bar
228 /// /foo/bar       => foo/bar
229 ///
230 /// @param path Input path.
231 /// @param result Set to the path starting after root_path if one exists,
232 ///               otherwise "".
233 /// @results errc::success if result has been successfully set, otherwise a
234 ///          platform specific error_code.
235 error_code relative_path(const StringRef &path, StringRef &result);
236
237 /// @brief Get parent path.
238 ///
239 /// /          => <empty>
240 /// /foo       => /
241 /// foo/../bar => foo/..
242 ///
243 /// @param path Input path.
244 /// @param result Set to the parent path of \a path if one exists, otherwise "".
245 /// @results errc::success if result has been successfully set, otherwise a
246 ///          platform specific error_code.
247 error_code parent_path(const StringRef &path, StringRef &result);
248
249 /// @brief Get filename.
250 ///
251 /// /foo.txt    => foo.txt
252 /// .          => .
253 /// ..         => ..
254 /// /          => /
255 ///
256 /// @param path Input path.
257 /// @param result Set to the filename part of \a path. This is defined as the
258 ///               last component of \a path.
259 /// @results errc::success if result has been successfully set, otherwise a
260 ///          platform specific error_code.
261 error_code filename(const StringRef &path, StringRef &result);
262
263 /// @brief Get stem.
264 ///
265 /// If filename contains a dot but not solely one or two dots, result is the
266 /// substring of filename ending at (but not including) the last dot. Otherwise
267 /// it is filename.
268 ///
269 /// /foo/bar.txt => bar
270 /// /foo/bar     => bar
271 /// /foo/.txt    => <empty>
272 /// /foo/.       => .
273 /// /foo/..      => ..
274 ///
275 /// @param path Input path.
276 /// @param result Set to the stem of \a path.
277 /// @results errc::success if result has been successfully set, otherwise a
278 ///          platform specific error_code.
279 error_code stem(const StringRef &path, StringRef &result);
280
281 /// @brief Get extension.
282 ///
283 /// If filename contains a dot but not solely one or two dots, result is the
284 /// substring of filename starting at (and including) the last dot, and ending
285 /// at the end of \a path. Otherwise "".
286 ///
287 /// /foo/bar.txt => .txt
288 /// /foo/bar     => <empty>
289 /// /foo/.txt    => .txt
290 ///
291 /// @param path Input path.
292 /// @param result Set to the extension of \a path.
293 /// @results errc::success if result has been successfully set, otherwise a
294 ///          platform specific error_code.
295 error_code extension(const StringRef &path, StringRef &result);
296
297 /// @brief Has root name?
298 ///
299 /// root_name != ""
300 ///
301 /// @param path Input path.
302 /// @param result Set to true if the path has a root name, false otherwise.
303 /// @results errc::success if result has been successfully set, otherwise a
304 ///          platform specific error_code.
305 error_code has_root_name(const Twine &path, bool &result);
306
307 /// @brief Has root directory?
308 ///
309 /// root_directory != ""
310 ///
311 /// @param path Input path.
312 /// @param result Set to true if the path has a root directory, false otherwise.
313 /// @results errc::success if result has been successfully set, otherwise a
314 ///          platform specific error_code.
315 error_code has_root_directory(const Twine &path, bool &result);
316
317 /// @brief Has root path?
318 ///
319 /// root_path != ""
320 ///
321 /// @param path Input path.
322 /// @param result Set to true if the path has a root path, false otherwise.
323 /// @results errc::success if result has been successfully set, otherwise a
324 ///          platform specific error_code.
325 error_code has_root_path(const Twine &path, bool &result);
326
327 /// @brief Has relative path?
328 ///
329 /// relative_path != ""
330 ///
331 /// @param path Input path.
332 /// @param result Set to true if the path has a relative path, false otherwise.
333 /// @results errc::success if result has been successfully set, otherwise a
334 ///          platform specific error_code.
335 error_code has_relative_path(const Twine &path, bool &result);
336
337 /// @brief Has parent path?
338 ///
339 /// parent_path != ""
340 ///
341 /// @param path Input path.
342 /// @param result Set to true if the path has a parent path, false otherwise.
343 /// @results errc::success if result has been successfully set, otherwise a
344 ///          platform specific error_code.
345 error_code has_parent_path(const Twine &path, bool &result);
346
347 /// @brief Has filename?
348 ///
349 /// filename != ""
350 ///
351 /// @param path Input path.
352 /// @param result Set to true if the path has a filename, false otherwise.
353 /// @results errc::success if result has been successfully set, otherwise a
354 ///          platform specific error_code.
355 error_code has_filename(const Twine &path, bool &result);
356
357 /// @brief Has stem?
358 ///
359 /// stem != ""
360 ///
361 /// @param path Input path.
362 /// @param result Set to true if the path has a stem, false otherwise.
363 /// @results errc::success if result has been successfully set, otherwise a
364 ///          platform specific error_code.
365 error_code has_stem(const Twine &path, bool &result);
366
367 /// @brief Has extension?
368 ///
369 /// extension != ""
370 ///
371 /// @param path Input path.
372 /// @param result Set to true if the path has a extension, false otherwise.
373 /// @results errc::success if result has been successfully set, otherwise a
374 ///          platform specific error_code.
375 error_code has_extension(const Twine &path, bool &result);
376
377 /// @brief Is path absolute?
378 ///
379 /// @param path Input path.
380 /// @param result Set to true if the path is absolute, false if it is not.
381 /// @results errc::success if result has been successfully set, otherwise a
382 ///          platform specific error_code.
383 error_code is_absolute(const Twine &path, bool &result);
384
385 /// @brief Is path relative?
386 ///
387 /// @param path Input path.
388 /// @param result Set to true if the path is relative, false if it is not.
389 /// @results errc::success if result has been successfully set, otherwise a
390 ///          platform specific error_code.
391 error_code is_relative(const Twine &path, bool &result);
392 // end purely lexical.
393
394 } // end namespace path
395
396 namespace fs {
397
398 /// file_type - An "enum class" enumeration for the file system's view of the
399 ///             type.
400 struct file_type {
401   enum _ {
402     status_error,
403     file_not_found,
404     regular_file,
405     directory_file,
406     symlink_file,
407     block_file,
408     character_file,
409     fifo_file,
410     socket_file,
411     type_unknown
412   };
413
414   file_type(_ v) : v_(v) {}
415   explicit file_type(int v) : v_(_(v)) {}
416   operator int() const {return v_;}
417
418 private:
419   int v_;
420 };
421
422 /// copy_option - An "enum class" enumeration of copy semantics for copy
423 ///               operations.
424 struct copy_option {
425   enum _ {
426     fail_if_exists,
427     overwrite_if_exists
428   };
429
430   copy_option(_ v) : v_(v) {}
431   explicit copy_option(int v) : v_(_(v)) {}
432   operator int() const {return v_;}
433
434 private:
435   int v_;
436 };
437
438 /// space_info - Self explanatory.
439 struct space_info {
440   uint64_t capacity;
441   uint64_t free;
442   uint64_t available;
443 };
444
445 /// file_status - Represents the result of a call to stat and friends. It has
446 ///               a platform specific member to store the result.
447 class file_status
448 {
449   // implementation defined status field.
450 public:
451   explicit file_status(file_type v=file_type::status_error);
452
453   file_type type() const;
454   void type(file_type v);
455 };
456
457 /// @}
458 /// @name Physical Operators
459 /// @{
460
461 /// @brief Copy the file at \a from to the path \a to.
462 ///
463 /// @param from The path to copy the file from.
464 /// @param to The path to copy the file to.
465 /// @param copt Behavior if \a to already exists.
466 /// @returns errc::success if the file has been successfully copied.
467 ///          errc::file_exists if \a to already exists and \a copt ==
468 ///          copy_option::fail_if_exists. Otherwise a platform specific
469 ///          error_code.
470 error_code copy_file(const Twine &from, const Twine &to,
471                      copy_option copt = copy_option::fail_if_exists);
472
473 /// @brief Create all the non-existent directories in path.
474 ///
475 /// @param path Directories to create.
476 /// @param existed Set to true if \a path already existed, false otherwise.
477 /// @returns errc::success if is_directory(path) and existed have been set,
478 ///          otherwise a platform specific error_code.
479 error_code create_directories(const Twine &path, bool &existed);
480
481 /// @brief Create the directory in path.
482 ///
483 /// @param path Directory to create.
484 /// @param existed Set to true if \a path already existed, false otherwise.
485 /// @returns errc::success if is_directory(path) and existed have been set,
486 ///          otherwise a platform specific error_code.
487 error_code create_directory(const Twine &path, bool &existed);
488
489 /// @brief Create a hard link from \a from to \a to.
490 ///
491 /// @param to The path to hard link to.
492 /// @param from The path to hard link from. This is created.
493 /// @returns errc::success if exists(to) && exists(from) && equivalent(to, from)
494 ///          , otherwise a platform specific error_code.
495 error_code create_hard_link(const Twine &to, const Twine &from);
496
497 /// @brief Create a symbolic link from \a from to \a to.
498 ///
499 /// @param to The path to symbolically link to.
500 /// @param from The path to symbolically link from. This is created.
501 /// @returns errc::success if exists(to) && exists(from) && is_symlink(from),
502 ///          otherwise a platform specific error_code.
503 error_code create_symlink(const Twine &to, const Twine &from);
504
505 /// @brief Remove path. Equivalent to POSIX remove().
506 ///
507 /// @param path Input path.
508 /// @param existed Set to true if \a path existed, false if it did not.
509 ///                undefined otherwise.
510 /// @results errc::success if path has been removed and existed has been
511 ///          successfully set, otherwise a platform specific error_code.
512 error_code remove(const Twine &path, bool &existed);
513
514 /// @brief Recursively remove all files below \a path, then \a path. Files are
515 ///        removed as if by POSIX remove().
516 ///
517 /// @param path Input path.
518 /// @param num_removed Number of files removed.
519 /// @results errc::success if path has been removed and num_removed has been
520 ///          successfully set, otherwise a platform specific error_code.
521 error_code remove_all(const Twine &path, uint32_t &num_removed);
522
523 /// @brief Rename \a from to \a to. Files are renamed as if by POSIX rename().
524 ///
525 /// @param from The path to rename from.
526 /// @param to The path to rename to. This is created.
527 error_code rename(const Twine &from, const Twine &to);
528
529 /// @brief Resize path to size. File is resized as if by POSIX truncate().
530 ///
531 /// @param path Input path.
532 /// @param size Size to resize to.
533 /// @returns errc::success if \a path has been resized to \a size, otherwise a
534 ///          platform specific error_code.
535 error_code resize_file(const Twine &path, uint64_t size);
536
537 /// @brief Make file readable.
538 ///
539 /// @param path Input path.
540 /// @param value If true, make readable, else, make unreadable.
541 /// @results errc::success if readability has been successfully set, otherwise a
542 ///          platform specific error_code.
543 error_code set_read(const Twine &path, bool value);
544
545 /// @brief Make file writeable.
546 ///
547 /// @param path Input path.
548 /// @param value If true, make writeable, else, make unwriteable.
549 /// @results errc::success if writeability has been successfully set, otherwise
550 ///          a platform specific error_code.
551 error_code set_write(const Twine &path, bool value);
552
553 /// @brief Make file executable.
554 ///
555 /// @param path Input path.
556 /// @param value If true, make executable, else, make unexecutable.
557 /// @results errc::success if executability has been successfully set, otherwise
558 ///          a platform specific error_code.
559 error_code set_execute(const Twine &path, bool value);
560
561 /// @}
562 /// @name Physical Observers
563 /// @{
564
565 /// @brief Does file exist?
566 ///
567 /// @param status A file_status previously returned from stat.
568 /// @param result Set to true if the file represented by status exists, false if
569 ///               it does not. Undefined otherwise.
570 /// @results errc::success if result has been successfully set, otherwise a
571 ///          platform specific error_code.
572 error_code exists(file_status status, bool &result);
573
574 /// @brief Does file exist?
575 ///
576 /// @param path Input path.
577 /// @param result Set to true if the file represented by status exists, false if
578 ///               it does not. Undefined otherwise.
579 /// @results errc::success if result has been successfully set, otherwise a
580 ///          platform specific error_code.
581 error_code exists(const Twine &path, bool &result);
582
583 /// @brief Do paths represent the same thing?
584 ///
585 /// @param A Input path A.
586 /// @param B Input path B.
587 /// @param result Set to true if stat(A) and stat(B) have the same device and
588 ///               inode (or equivalent).
589 /// @results errc::success if result has been successfully set, otherwise a
590 ///          platform specific error_code.
591 error_code equivalent(const Twine &A, const Twine &B, bool &result);
592
593 /// @brief Get file size.
594 ///
595 /// @param path Input path.
596 /// @param result Set to the size of the file in \a path.
597 /// @returns errc::success if result has been successfully set, otherwise a
598 ///          platform specific error_code.
599 error_code file_size(const Twine &path, uint64_t &result);
600
601 /// @brief Does status represent a directory?
602 ///
603 /// @param status A file_status previously returned from stat.
604 /// @param result Set to true if the file represented by status is a directory,
605 ///               false if it is not. Undefined otherwise.
606 /// @results errc::success if result has been successfully set, otherwise a
607 ///          platform specific error_code.
608 error_code is_directory(file_status status, bool &result);
609
610 /// @brief Is path a directory?
611 ///
612 /// @param path Input path.
613 /// @param result Set to true if \a path is a directory, false if it is not.
614 ///               Undefined otherwise.
615 /// @results errc::success if result has been successfully set, otherwise a
616 ///          platform specific error_code.
617 error_code is_directory(const Twine &path, bool &result);
618
619 /// @brief Is path an empty file?
620 ///
621 /// @param path Input path.
622 /// @param result Set to true if \a path is a an empty file, false if it is not.
623 ///               Undefined otherwise.
624 /// @results errc::success if result has been successfully set, otherwise a
625 ///          platform specific error_code.
626 error_code is_empty(const Twine &path, bool &result);
627
628 /// @brief Does status represent a regular file?
629 ///
630 /// @param status A file_status previously returned from stat.
631 /// @param result Set to true if the file represented by status is a regular
632 ///               file, false if it is not. Undefined otherwise.
633 /// @results errc::success if result has been successfully set, otherwise a
634 ///          platform specific error_code.
635 error_code is_regular_file(file_status status, bool &result);
636
637 /// @brief Is path a regular file?
638 ///
639 /// @param path Input path.
640 /// @param result Set to true if \a path is a regular file, false if it is not.
641 ///               Undefined otherwise.
642 /// @results errc::success if result has been successfully set, otherwise a
643 ///          platform specific error_code.
644 error_code is_regular_file(const Twine &path, bool &result);
645
646 /// @brief Does status represent something that exists but is not a directory,
647 ///        regular file, or symlink?
648 ///
649 /// @param status A file_status previously returned from stat.
650 /// @param result Set to true if the file represented by status exists, but is
651 ///               not a directory, regular file, or a symlink, false if it does
652 ///               not. Undefined otherwise.
653 /// @results errc::success if result has been successfully set, otherwise a
654 ///          platform specific error_code.
655 error_code is_other(file_status status, bool &result);
656
657 /// @brief Is path something that exists but is not a directory,
658 ///        regular file, or symlink?
659 ///
660 /// @param path Input path.
661 /// @param result Set to true if \a path exists, but is not a directory, regular
662 ///               file, or a symlink, false if it does not. Undefined otherwise.
663 /// @results errc::success if result has been successfully set, otherwise a
664 ///          platform specific error_code.
665 error_code is_other(const Twine &path, bool &result);
666
667 /// @brief Does status represent a symlink?
668 ///
669 /// @param status A file_status previously returned from stat.
670 /// @param result Set to true if the file represented by status is a symlink,
671 ///               false if it is not. Undefined otherwise.
672 /// @results errc::success if result has been successfully set, otherwise a
673 ///          platform specific error_code.
674 error_code is_symlink(file_status status, bool &result);
675
676 /// @brief Is path a symlink?
677 ///
678 /// @param path Input path.
679 /// @param result Set to true if \a path is a symlink, false if it is not.
680 ///               Undefined otherwise.
681 /// @results errc::success if result has been successfully set, otherwise a
682 ///          platform specific error_code.
683 error_code is_symlink(const Twine &path, bool &result);
684
685 /// @brief Get last write time without changing it.
686 ///
687 /// @param path Input path.
688 /// @param result Set to the last write time (UNIX time) of \a path if it
689 ///               exists.
690 /// @results errc::success if result has been successfully set, otherwise a
691 ///          platform specific error_code.
692 error_code last_write_time(const Twine &path, std::time_t &result);
693
694 /// @brief Set last write time.
695 ///
696 /// @param path Input path.
697 /// @param value Time to set (UNIX time) \a path's last write time to.
698 /// @results errc::success if result has been successfully set, otherwise a
699 ///          platform specific error_code.
700 error_code set_last_write_time(const Twine &path, std::time_t value);
701
702 /// @brief Read a symlink's value.
703 ///
704 /// @param path Input path.
705 /// @param result Set to the value of the symbolic link \a path.
706 /// @results errc::success if result has been successfully set, otherwise a
707 ///          platform specific error_code.
708 error_code read_symlink(const Twine &path, SmallVectorImpl<char> &result);
709
710 /// @brief Get disk space usage information.
711 ///
712 /// @param path Input path.
713 /// @param result Set to the capacity, free, and available space on the device
714 ///               \a path is on.
715 /// @results errc::success if result has been successfully set, otherwise a
716 ///          platform specific error_code.
717 error_code disk_space(const Twine &path, space_info &result);
718
719 /// @brief Get file status as if by POSIX stat().
720 ///
721 /// @param path Input path.
722 /// @param result Set to the file status.
723 /// @results errc::success if result has been successfully set, otherwise a
724 ///          platform specific error_code.
725 error_code status(const Twine &path, file_status &result);
726
727 /// @brief Is status available?
728 ///
729 /// @param path Input path.
730 /// @param result Set to true if status() != status_error.
731 /// @results errc::success if result has been successfully set, otherwise a
732 ///          platform specific error_code.
733 error_code status_known(const Twine &path, bool &result);
734
735 /// @brief Get file status as if by POSIX lstat().
736 ///
737 /// Does not resolve symlinks.
738 ///
739 /// @param path Input path.
740 /// @param result Set to the file status.
741 /// @results errc::success if result has been successfully set, otherwise a
742 ///          platform specific error_code.
743 error_code symlink_status(const Twine &path, file_status &result);
744
745 /// @brief Get the temporary directory.
746 ///
747 /// @param result Set to the temporary directory.
748 /// @results errc::success if result has been successfully set, otherwise a
749 ///          platform specific error_code.
750 /// @see unique_file
751 error_code temp_directory_path(SmallVectorImpl<char> &result);
752
753 /// @brief Generate a unique path and open it as a file.
754 ///
755 /// Generates a unique path suitable for a temporary file and then opens it as a
756 /// file. The name is based on \a model with '%' replaced by a random char in
757 /// [0-9a-f].
758 ///
759 /// This is an atomic operation. Either the file is created and opened, or the
760 /// file system is left untouched.
761 ///
762 /// clang-%%-%%-%%-%%-%%.s => <current-directory>/clang-a0-b1-c2-d3-e4.s
763 ///
764 /// @param model Name to base unique path off of.
765 /// @param result Set to the opened file.
766 /// @results errc::success if result has been successfully set, otherwise a
767 ///          platform specific error_code.
768 /// @see temp_directory_path
769 error_code unique_file(const Twine &model, void* i_have_not_decided_the_ty_yet);
770
771 /// @brief Canonicalize path.
772 ///
773 /// Sets result to the file system's idea of what path is. The result is always
774 /// absolute and has the same capitalization as the file system.
775 ///
776 /// @param path Input path.
777 /// @param result Set to the canonicalized version of \a path.
778 /// @results errc::success if result has been successfully set, otherwise a
779 ///          platform specific error_code.
780 error_code canonicalize(const Twine &path, SmallVectorImpl<char> &result);
781
782 /// @brief Are \a path's first bytes \a magic?
783 ///
784 /// @param path Input path.
785 /// @param magic Byte sequence to compare \a path's first len(magic) bytes to.
786 /// @results errc::success if result has been successfully set, otherwise a
787 ///          platform specific error_code.
788 error_code has_magic(const Twine &path, const Twine &magic);
789
790 /// @brief Get \a path's first \a len bytes.
791 ///
792 /// @param path Input path.
793 /// @param len Number of magic bytes to get.
794 /// @param result Set to the first \a len bytes in the file pointed to by
795 ///               \a path.
796 /// @results errc::success if result has been successfully set, otherwise a
797 ///          platform specific error_code.
798 error_code get_magic(const Twine &path, uint32_t len,
799                      SmallVectorImpl<char> &result);
800
801 /// @brief Is file bitcode?
802 ///
803 /// @param path Input path.
804 /// @param result Set to true if \a path is a bitcode file, false if it is not,
805 ///               undefined otherwise.
806 /// @results errc::success if result has been successfully set, otherwise a
807 ///          platform specific error_code.
808 error_code is_bitcode(const Twine &path, bool &result);
809
810 /// @brief Is file a dynamic library?
811 ///
812 /// @param path Input path.
813 /// @param result Set to true if \a path is a dynamic library, false if it is
814 ///               not, undefined otherwise.
815 /// @results errc::success if result has been successfully set, otherwise a
816 ///          platform specific error_code.
817 error_code is_dynamic_library(const Twine &path, bool &result);
818
819 /// @brief Is an object file?
820 ///
821 /// @param path Input path.
822 /// @param result Set to true if \a path is an object file, false if it is not,
823 ///               undefined otherwise.
824 /// @results errc::success if result has been successfully set, otherwise a
825 ///          platform specific error_code.
826 error_code is_object_file(const Twine &path, bool &result);
827
828 /// @brief Can file be read?
829 ///
830 /// @param path Input path.
831 /// @param result Set to true if \a path is readable, false it it is not,
832 ///               undefined otherwise.
833 /// @results errc::success if result has been successfully set, otherwise a
834 ///          platform specific error_code.
835 error_code can_read(const Twine &path, bool &result);
836
837 /// @brief Can file be written?
838 ///
839 /// @param path Input path.
840 /// @param result Set to true if \a path is writeable, false it it is not,
841 ///               undefined otherwise.
842 /// @results errc::success if result has been successfully set, otherwise a
843 ///          platform specific error_code.
844 error_code can_write(const Twine &path, bool &result);
845
846 /// @brief Can file be executed?
847 ///
848 /// @param path Input path.
849 /// @param result Set to true if \a path is executable, false it it is not,
850 ///               undefined otherwise.
851 /// @results errc::success if result has been successfully set, otherwise a
852 ///          platform specific error_code.
853 error_code can_execute(const Twine &path, bool &result);
854
855 /// @brief Get library paths the system linker uses.
856 ///
857 /// @param result Set to the list of system library paths.
858 /// @results errc::success if result has been successfully set, otherwise a
859 ///          platform specific error_code.
860 error_code GetSystemLibraryPaths(SmallVectorImpl<std::string> &result);
861
862 /// @brief Get bitcode library paths the system linker uses
863 ///        + LLVM_LIB_SEARCH_PATH + LLVM_LIBDIR.
864 ///
865 /// @param result Set to the list of bitcode library paths.
866 /// @results errc::success if result has been successfully set, otherwise a
867 ///          platform specific error_code.
868 error_code GetBitcodeLibraryPaths(SmallVectorImpl<std::string> &result);
869
870 /// @brief Find a library.
871 ///
872 /// Find the path to a library using its short name. Use the system
873 /// dependent library paths to locate the library.
874 ///
875 /// c => /usr/lib/libc.so
876 ///
877 /// @param short_name Library name one would give to the system linker.
878 /// @param result Set to the absolute path \a short_name represents.
879 /// @results errc::success if result has been successfully set, otherwise a
880 ///          platform specific error_code.
881 error_code FindLibrary(const Twine &short_name, SmallVectorImpl<char> &result);
882
883 /// @brief Get absolute path of main executable.
884 ///
885 /// @param argv0 The program name as it was spelled on the command line.
886 /// @param MainAddr Address of some symbol in the executable (not in a library).
887 /// @param result Set to the absolute path of the current executable.
888 /// @results errc::success if result has been successfully set, otherwise a
889 ///          platform specific error_code.
890 error_code GetMainExecutable(const char *argv0, void *MainAddr,
891                              SmallVectorImpl<char> &result);
892
893 /// @}
894 /// @name Iterators
895 /// @{
896
897 /// directory_entry - A single entry in a directory. Caches the status either
898 /// from the result of the iteration syscall, or the first time status or
899 /// symlink_status is called.
900 class directory_entry {
901   std::string Path;
902   mutable file_status Status;
903   mutable file_status SymlinkStatus;
904
905 public:
906   explicit directory_entry(const Twine &path, file_status st = file_status(),
907                                        file_status symlink_st = file_status());
908
909   void assign(const Twine &path, file_status st = file_status(),
910                           file_status symlink_st = file_status());
911   void replace_filename(const Twine &filename, file_status st = file_status(),
912                               file_status symlink_st = file_status());
913
914   const SmallVectorImpl<char> &path() const;
915   error_code status(file_status &result) const;
916   error_code symlink_status(file_status &result) const;
917
918   bool operator==(const directory_entry& rhs) const;
919   bool operator!=(const directory_entry& rhs) const;
920   bool operator< (const directory_entry& rhs) const;
921   bool operator<=(const directory_entry& rhs) const;
922   bool operator> (const directory_entry& rhs) const;
923   bool operator>=(const directory_entry& rhs) const;
924 };
925
926 /// directory_iterator - Iterates through the entries in path. There is no
927 /// operator++ because we need an error_code. If it's really needed we can make
928 /// it call report_fatal_error on error.
929 class directory_iterator {
930   // implementation directory iterator status
931
932 public:
933   explicit directory_iterator(const Twine &path, error_code &ec);
934   // No operator++ because we need error_code.
935   directory_iterator &increment(error_code &ec);
936
937   const directory_entry &operator*() const;
938   const directory_entry *operator->() const;
939
940   // Other members as required by
941   // C++ Std, 24.1.1 Input iterators [input.iterators]
942 };
943
944 /// recursive_directory_iterator - Same as directory_iterator except for it
945 /// recurses down into child directories.
946 class recursive_directory_iterator {
947   uint16_t  Level;
948   bool HasNoPushRequest;
949   // implementation directory iterator status
950
951 public:
952   explicit recursive_directory_iterator(const Twine &path, error_code &ec);
953   // No operator++ because we need error_code.
954   directory_iterator &increment(error_code &ec);
955
956   const directory_entry &operator*() const;
957   const directory_entry *operator->() const;
958
959   // observers
960   /// Gets the current level. path is at level 0.
961   int level() const;
962   /// Returns true if no_push has been called for this directory_entry.
963   bool no_push_request() const;
964
965   // modifiers
966   /// Goes up one level if Level > 0.
967   void pop();
968   /// Does not go down into the current directory_entry.
969   void no_push();
970
971   // Other members as required by
972   // C++ Std, 24.1.1 Input iterators [input.iterators]
973 };
974
975 /// @}
976
977 } // end namespace fs
978 } // end namespace sys
979 } // end namespace llvm