Mercurial > molko
annotate libmlk-util/mlk/util/dir.h @ 570:aaf518c87628
util: introduce dir module
author | David Demelier <markand@malikania.fr> |
---|---|
date | Thu, 09 Mar 2023 20:30:00 +0100 |
parents | |
children | f937857336f3 |
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 */ |