Mercurial > molko

comparison libmlk-util/mlk/util/dir.h @ 570:aaf518c87628

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
util: introduce dir module
author David Demelier <markand@malikania.fr>
date Thu, 09 Mar 2023 20:30:00 +0100
parents
children f937857336f3
comparison
equal deleted inserted replaced
569:e13d79a14791 570:aaf518c87628
1 /*
2 * dir.h -- portable directory iterator
3 *
4 * Copyright (c) 2020-2023 David Demelier <markand@malikania.fr>
5 *
6 * Permission to use, copy, modify, and/or distribute this software for any
7 * purpose with or without fee is hereby granted, provided that the above
8 * copyright notice and this permission notice appear in all copies.
9 *
10 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 */
18
19 #ifndef MLK_UTIL_DIR_H
20 #define MLK_UTIL_DIR_H
21
22 /**
23 * \file dir.h
24 * \brief Portable directory iterator
25 *
26 * This module provides a convenient portable directory iterator.
27 *
28 * How to use:
29 *
30 * 1. Use ::mlk_dir_open on your directory.
31 * 2. Call ::mlk_dir_next in a loop.
32 *
33 * The iterator is destroyed when the last iterator value has been read
34 * otherwise ::mlk_dir_finish can be used in case the loop was terminated early
35 *
36 * ```c
37 * struct mlk_dir_iter iter;
38 *
39 * if (mlk_dir_open(&iter, "/tmp") < 0) {
40 * fprintf(stderr, "unable to open the directory\n");
41 * return -1;
42 * }
43 *
44 * while (mlk_dir_next(&iter)) {
45 * printf("-> %s\n", iter->entry);
46 * }
47 *
48 * // At this step the directory iterator is already destroyed for convenience.
49 * ```
50 */
51
52 #if defined(__cplusplus)
53 extern "C" {
54 #endif
55
56 /**
57 * \struct mlk_dir_iter
58 * \brief Directory iterator structure
59 */
60 struct mlk_dir_iter {
61 /**
62 * (read-only, borrowed)
63 *
64 * Relative directory file entry name.
65 */
66 const char *entry;
67
68 /** \cond MLK_PRIVATE_DECLS */
69 void *handle;
70 /** \endcond MLK_PRIVATE_DECLS */
71 };
72
73 /**
74 * Open the directory iterator specified by path.
75 *
76 * \pre iter != NULL
77 * \pre path != NULL
78 * \param iter the iterator to initialize
79 * \param path the path to the directory
80 * \return 0 on success or -1 on error
81 */
82 int
83 mlk_dir_open(struct mlk_dir_iter *iter, const char *path);
84
85 /**
86 * Read the next directory entry.
87 *
88 * \pre iter != NULL
89 * \param iter the directory iterator
90 * \return 1 on read or 0 on EOF
91 */
92 int
93 mlk_dir_next(struct mlk_dir_iter *iter);
94
95 /**
96 * Cleanup directory iterator resources.
97 *
98 * This function is only required if you didn't complete the loop using
99 * ::mlk_dir_next function.
100 *
101 * \pre iter != NULL
102 * \param iter the directory iterator
103 */
104 void
105 mlk_dir_finish(struct mlk_dir_iter *iter);
106
107 #if defined(__cplusplus)
108 }
109 #endif
110
111 #endif /* !MLK_UTIL_DIR_H */