| 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 */ |