Mercurial > molko

annotate libmlk-util/mlk/util/dir.h @ 574:8cf895e51fb6

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