THIS IS A TEST INSTANCE ONLY! REPOSITORIES CAN BE DELETED AT ANY TIME!

Git Source Code Mirror - This is a publish-only repository and all pull requests are ignored. Please follow Documentation/SubmittingPatches procedure for any of your improvements.
git
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

128 lines
4.3KB

  1. #ifndef DIR_ITERATOR_H
  2. #define DIR_ITERATOR_H
  3. #include "strbuf.h"
  4. /*
  5. * Iterate over a directory tree.
  6. *
  7. * Iterate over a directory tree, recursively, including paths of all
  8. * types and hidden paths. Skip "." and ".." entries and don't follow
  9. * symlinks except for the original path. Note that the original path
  10. * is not included in the iteration.
  11. *
  12. * Every time dir_iterator_advance() is called, update the members of
  13. * the dir_iterator structure to reflect the next path in the
  14. * iteration. The order that paths are iterated over within a
  15. * directory is undefined, directory paths are always given before
  16. * their contents.
  17. *
  18. * A typical iteration looks like this:
  19. *
  20. * int ok;
  21. * unsigned int flags = DIR_ITERATOR_PEDANTIC;
  22. * struct dir_iterator *iter = dir_iterator_begin(path, flags);
  23. *
  24. * if (!iter)
  25. * goto error_handler;
  26. *
  27. * while ((ok = dir_iterator_advance(iter)) == ITER_OK) {
  28. * if (want_to_stop_iteration()) {
  29. * ok = dir_iterator_abort(iter);
  30. * break;
  31. * }
  32. *
  33. * // Access information about the current path:
  34. * if (S_ISDIR(iter->st.st_mode))
  35. * printf("%s is a directory\n", iter->relative_path);
  36. * }
  37. *
  38. * if (ok != ITER_DONE)
  39. * handle_error();
  40. *
  41. * Callers are allowed to modify iter->path while they are working,
  42. * but they must restore it to its original contents before calling
  43. * dir_iterator_advance() again.
  44. */
  45. /*
  46. * Flags for dir_iterator_begin:
  47. *
  48. * - DIR_ITERATOR_PEDANTIC: override dir-iterator's default behavior
  49. * in case of an error at dir_iterator_advance(), which is to keep
  50. * looking for a next valid entry. With this flag, resources are freed
  51. * and ITER_ERROR is returned immediately. In both cases, a meaningful
  52. * warning is emitted. Note: ENOENT errors are always ignored so that
  53. * the API users may remove files during iteration.
  54. *
  55. * - DIR_ITERATOR_FOLLOW_SYMLINKS: make dir-iterator follow symlinks.
  56. * i.e., linked directories' contents will be iterated over and
  57. * iter->base.st will contain information on the referred files,
  58. * not the symlinks themselves, which is the default behavior. Broken
  59. * symlinks are ignored.
  60. *
  61. * Warning: circular symlinks are also followed when
  62. * DIR_ITERATOR_FOLLOW_SYMLINKS is set. The iteration may end up with
  63. * an ELOOP if they happen and DIR_ITERATOR_PEDANTIC is set.
  64. */
  65. #define DIR_ITERATOR_PEDANTIC (1 << 0)
  66. #define DIR_ITERATOR_FOLLOW_SYMLINKS (1 << 1)
  67. struct dir_iterator {
  68. /* The current path: */
  69. struct strbuf path;
  70. /*
  71. * The current path relative to the starting path. This part
  72. * of the path always uses "/" characters to separate path
  73. * components:
  74. */
  75. const char *relative_path;
  76. /* The current basename: */
  77. const char *basename;
  78. /*
  79. * The result of calling lstat() on path; or stat(), if the
  80. * DIR_ITERATOR_FOLLOW_SYMLINKS flag was set at
  81. * dir_iterator's initialization.
  82. */
  83. struct stat st;
  84. };
  85. /*
  86. * Start a directory iteration over path with the combination of
  87. * options specified by flags. On success, return a dir_iterator
  88. * that holds the internal state of the iteration. In case of
  89. * failure, return NULL and set errno accordingly.
  90. *
  91. * The iteration includes all paths under path, not including path
  92. * itself and not including "." or ".." entries.
  93. *
  94. * Parameters are:
  95. * - path is the starting directory. An internal copy will be made.
  96. * - flags is a combination of the possible flags to initialize a
  97. * dir-iterator or 0 for default behavior.
  98. */
  99. struct dir_iterator *dir_iterator_begin(const char *path, unsigned int flags);
  100. /*
  101. * Advance the iterator to the first or next item and return ITER_OK.
  102. * If the iteration is exhausted, free the dir_iterator and any
  103. * resources associated with it and return ITER_DONE.
  104. *
  105. * It is a bug to use iterator or call this function again after it
  106. * has returned ITER_DONE or ITER_ERROR (which may be returned iff
  107. * the DIR_ITERATOR_PEDANTIC flag was set).
  108. */
  109. int dir_iterator_advance(struct dir_iterator *iterator);
  110. /*
  111. * End the iteration before it has been exhausted. Free the
  112. * dir_iterator and any associated resources and return ITER_DONE. On
  113. * error, free the dir_iterator and return ITER_ERROR.
  114. */
  115. int dir_iterator_abort(struct dir_iterator *iterator);
  116. #endif