Debian Codegraph @

libdrgn/path.h

raw
1 // Copyright (c) Meta Platforms, Inc. and affiliates.
2 // SPDX-License-Identifier: LGPL-2.1-or-later
3
4 /**
5 * @file
6 *
7 * Paths.
8 *
9 * See @ref Paths.
10 */
11
12 #ifndef DRGN_PATH_H
13 #define DRGN_PATH_H
14
15 #include <elfutils/libdw.h>
16 #include <stdbool.h>
17 #include <stddef.h>
18
19 #include "nstring.h" // IWYU pragma: export
20
21 /**
22 * @ingroup Internals
23 *
24 * @defgroup Paths Paths
25 *
26 * Utilities for working with paths.
27 *
28 * @{
29 */
30
31 /**
32 * Path component iterator.
33 *
34 * This iterates over the components of a file path, joining multiple components
35 * and normalizing the result. Normalization:
36 *
37 * - Collapses redundant "/" separators.
38 * - Removes "." components.
39 * - Removes ".." components when possible.
40 *
41 * Components are emitted in @b reverse. So, "a/b/c" is emitted in the order
42 * "c", "b", "a" (this allows the implementation to operate in O(n) time and
43 * O(1) space).
44 *
45 * Absolute paths have an implicit empty component, so "/a/b" is emitted as "b",
46 * "a", "".
47 *
48 * Relative paths are emitted relative to a hypothetical current directory. A
49 * path referring to the current directory (e.g., "." or "a/..") does not emit
50 * any components.
51 *
52 * ".." components above the current directory are included, so "a/b/../../../c"
53 * is emitted as "c", "..". However, ".." components above an absolute path are
54 * not meaningful, so "/a/b/../../../c" is emitted as "c", "".
55 *
56 * A empty path does not emit any components.
57 */
58 struct path_iterator {
59 /**
60 * Array of input components.
61 *
62 * The input components are treated as if they were joined with a "/".
63 * @ref nstring::str and @ref nstring::len should be initialized for
64 * each component. The latter will be modified as the path is iterated.
65 */
66 struct nstring *components;
67 /** Number of components in @ref path_iterator::components. */
68 size_t num_components;
69 /**
70 * Current number of ".." components.
71 *
72 * Initialize this to 0.
73 */
74 size_t dot_dot;
75 };
76
77 /**
78 * Get the next component from a @ref path_iterator.
79 *
80 * Components are emitted in reverse. This will never emit a "." component. It
81 * will emit an empty ("") component only for an absolute path. It may emit ".."
82 * components if there are any that go above the current directory.
83 *
84 * @param[in] it Iterator.
85 * @param[out] component_ret Returned component.
86 * @param[out] component_len_ret Length of @c component.
87 * @return @c true if we returned a componenent, @c false if there were no more
88 * components.
89 */
90 bool path_iterator_next(struct path_iterator *it, const char **component_ret,
91 size_t *component_len_ret);
92
93 /**
94 * Return whether the path @p haystack ends with the path @p needle once both
95 * are normalized.
96 *
97 * The unit of comparison is a path component, not a character. Thus, "ab/cd/ef"
98 * ends with "cd/ef", but not "d/ef".
99 *
100 * @sa path_iterator
101 */
102 bool path_ends_with(struct path_iterator *haystack,
103 struct path_iterator *needle);
104
105 bool die_matches_filename(Dwarf_Die *die, const char *filename);
106
107 /** @} */
108
109 #endif /* DRGN_PATH_H */