2 * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com>
4 * SPDX-License-Identifier: LGPL-2.1-only
8 #ifndef _COMPAT_DIRECTORY_HANDLE_H
9 #define _COMPAT_DIRECTORY_HANDLE_H
11 #include <common/credentials.hpp>
12 #include <common/macros.hpp>
16 enum lttng_directory_handle_rmdir_recursive_flags {
17 LTTNG_DIRECTORY_HANDLE_FAIL_NON_EMPTY_FLAG = (1U << 0),
18 LTTNG_DIRECTORY_HANDLE_SKIP_NON_EMPTY_FLAG = (1U << 1),
22 * Some platforms, such as Solaris 10, do not support directory file descriptors
23 * and their associated functions (*at(...)), which are defined in POSIX.2008.
25 * This wrapper provides a handle that is either a copy of a directory's path
26 * or a directory file descriptors, depending on the platform's capabilities.
30 struct lttng_directory_handle;
32 using lttng_directory_handle_destroy_cb = void (*)(struct lttng_directory_handle *, void *);
34 struct lttng_directory_handle {
36 ino_t directory_inode;
38 lttng_directory_handle_destroy_cb destroy_cb;
39 void *destroy_cb_data;
43 int lttng_directory_handle_get_dirfd(
44 const struct lttng_directory_handle *handle)
50 struct lttng_directory_handle {
57 * Create a directory handle to the provided path. Passing a NULL path
58 * returns a handle to the current working directory.
60 * The reference to the directory handle must be released using
61 * lttng_directory_handle_put().
63 struct lttng_directory_handle *lttng_directory_handle_create(
67 * Create a new directory handle to a path relative to an existing handle.
69 * The provided path must already exist. Note that the creation of a
70 * subdirectory and the creation of a handle are kept as separate operations
71 * to highlight the fact that there is an inherent race between the creation of
72 * a directory and the creation of a handle to it.
74 * Passing a NULL path effectively copies the original handle.
76 * The reference to the directory handle must be released using
77 * lttng_directory_handle_put().
79 struct lttng_directory_handle *lttng_directory_handle_create_from_handle(
81 const struct lttng_directory_handle *ref_handle);
84 * Create a new directory handle from an existing directory fd.
86 * The new directory handle assumes the ownership of the directory fd.
87 * Note that this method should only be used in very specific cases, such as
88 * re-creating a directory handle from a dirfd passed over a unix socket.
90 * The reference to the directory handle must be released using
91 * lttng_directory_handle_put().
93 struct lttng_directory_handle *lttng_directory_handle_create_from_dirfd(
97 * Copy a directory handle.
99 * The reference to the directory handle must be released using
100 * lttng_directory_handle_put().
102 struct lttng_directory_handle *lttng_directory_handle_copy(
103 const struct lttng_directory_handle *handle);
106 * Acquire a reference to a directory handle.
108 bool lttng_directory_handle_get(struct lttng_directory_handle *handle);
111 * Release a reference to a directory handle.
113 void lttng_directory_handle_put(struct lttng_directory_handle *handle);
116 * Create a subdirectory relative to a directory handle.
118 int lttng_directory_handle_create_subdirectory(
119 const struct lttng_directory_handle *handle,
120 const char *subdirectory,
124 * Create a subdirectory relative to a directory handle
127 int lttng_directory_handle_create_subdirectory_as_user(
128 const struct lttng_directory_handle *handle,
129 const char *subdirectory,
130 mode_t mode, const struct lttng_credentials *creds);
133 * Recursively create a directory relative to a directory handle.
135 int lttng_directory_handle_create_subdirectory_recursive(
136 const struct lttng_directory_handle *handle,
137 const char *subdirectory_path,
141 * Recursively create a directory relative to a directory handle
144 int lttng_directory_handle_create_subdirectory_recursive_as_user(
145 const struct lttng_directory_handle *handle,
146 const char *subdirectory_path,
147 mode_t mode, const struct lttng_credentials *creds);
150 * Open a file descriptor to a path relative to a directory handle.
152 int lttng_directory_handle_open_file(
153 const struct lttng_directory_handle *handle,
154 const char *filename,
155 int flags, mode_t mode);
158 * Open a file descriptor to a path relative to a directory handle
161 int lttng_directory_handle_open_file_as_user(
162 const struct lttng_directory_handle *handle,
163 const char *filename,
164 int flags, mode_t mode,
165 const struct lttng_credentials *creds);
168 * Unlink a file to a path relative to a directory handle.
170 int lttng_directory_handle_unlink_file(
171 const struct lttng_directory_handle *handle,
172 const char *filename);
175 * Unlink a file to a path relative to a directory handle as a given user.
177 int lttng_directory_handle_unlink_file_as_user(
178 const struct lttng_directory_handle *handle,
179 const char *filename,
180 const struct lttng_credentials *creds);
183 * Rename a file from a path relative to a directory handle to a new
184 * name relative to another directory handle.
186 int lttng_directory_handle_rename(
187 const struct lttng_directory_handle *old_handle,
188 const char *old_name,
189 const struct lttng_directory_handle *new_handle,
190 const char *new_name);
193 * Rename a file from a path relative to a directory handle to a new
194 * name relative to another directory handle as a given user.
196 int lttng_directory_handle_rename_as_user(
197 const struct lttng_directory_handle *old_handle,
198 const char *old_name,
199 const struct lttng_directory_handle *new_handle,
200 const char *new_name,
201 const struct lttng_credentials *creds);
204 * Remove a subdirectory relative to a directory handle.
206 int lttng_directory_handle_remove_subdirectory(
207 const struct lttng_directory_handle *handle,
211 * Remove a subdirectory relative to a directory handle as a given user.
213 int lttng_directory_handle_remove_subdirectory_as_user(
214 const struct lttng_directory_handle *handle,
216 const struct lttng_credentials *creds);
219 * Remove a subdirectory and remove its contents if it only
220 * consists in empty directories.
221 * @flags: enum lttng_directory_handle_rmdir_recursive_flags
223 int lttng_directory_handle_remove_subdirectory_recursive(
224 const struct lttng_directory_handle *handle,
225 const char *name, int flags);
228 * Remove a subdirectory and remove its contents if it only
229 * consists in empty directories as a given user.
230 * @flags: enum lttng_directory_handle_rmdir_recursive_flags
232 int lttng_directory_handle_remove_subdirectory_recursive_as_user(
233 const struct lttng_directory_handle *handle,
235 const struct lttng_credentials *creds,
239 * stat() a file relative to a directory handle.
241 int lttng_directory_handle_stat(
242 const struct lttng_directory_handle *handle,
244 struct stat *stat_buf);
247 * Returns true if this directory handle is backed by a file
248 * descriptor, false otherwise.
250 bool lttng_directory_handle_uses_fd(
251 const struct lttng_directory_handle *handle);
254 * Compare two directory handles.
256 * Returns true if the two directory handles are equal, false otherwise.
258 bool lttng_directory_handle_equals(const struct lttng_directory_handle *lhs,
259 const struct lttng_directory_handle *rhs);
262 #endif /* _COMPAT_PATH_HANDLE_H */