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 typedef void (*lttng_directory_handle_destroy_cb)(
33 struct lttng_directory_handle *handle, void *data);
35 struct lttng_directory_handle {
37 ino_t directory_inode;
39 lttng_directory_handle_destroy_cb destroy_cb;
40 void *destroy_cb_data;
44 int lttng_directory_handle_get_dirfd(
45 const struct lttng_directory_handle *handle)
51 struct lttng_directory_handle {
58 * Create a directory handle to the provided path. Passing a NULL path
59 * returns a handle to the current working directory.
61 * The reference to the directory handle must be released using
62 * lttng_directory_handle_put().
64 struct lttng_directory_handle *lttng_directory_handle_create(
68 * Create a new directory handle to a path relative to an existing handle.
70 * The provided path must already exist. Note that the creation of a
71 * subdirectory and the creation of a handle are kept as separate operations
72 * to highlight the fact that there is an inherent race between the creation of
73 * a directory and the creation of a handle to it.
75 * Passing a NULL path effectively copies the original handle.
77 * The reference to the directory handle must be released using
78 * lttng_directory_handle_put().
80 struct lttng_directory_handle *lttng_directory_handle_create_from_handle(
82 const struct lttng_directory_handle *ref_handle);
85 * Create a new directory handle from an existing directory fd.
87 * The new directory handle assumes the ownership of the directory fd.
88 * Note that this method should only be used in very specific cases, such as
89 * re-creating a directory handle from a dirfd passed over a unix socket.
91 * The reference to the directory handle must be released using
92 * lttng_directory_handle_put().
94 struct lttng_directory_handle *lttng_directory_handle_create_from_dirfd(
98 * Copy a directory handle.
100 * The reference to the directory handle must be released using
101 * lttng_directory_handle_put().
103 struct lttng_directory_handle *lttng_directory_handle_copy(
104 const struct lttng_directory_handle *handle);
107 * Acquire a reference to a directory handle.
109 bool lttng_directory_handle_get(struct lttng_directory_handle *handle);
112 * Release a reference to a directory handle.
114 void lttng_directory_handle_put(struct lttng_directory_handle *handle);
117 * Create a subdirectory relative to a directory handle.
119 int lttng_directory_handle_create_subdirectory(
120 const struct lttng_directory_handle *handle,
121 const char *subdirectory,
125 * Create a subdirectory relative to a directory handle
128 int lttng_directory_handle_create_subdirectory_as_user(
129 const struct lttng_directory_handle *handle,
130 const char *subdirectory,
131 mode_t mode, const struct lttng_credentials *creds);
134 * Recursively create a directory relative to a directory handle.
136 int lttng_directory_handle_create_subdirectory_recursive(
137 const struct lttng_directory_handle *handle,
138 const char *subdirectory_path,
142 * Recursively create a directory relative to a directory handle
145 int lttng_directory_handle_create_subdirectory_recursive_as_user(
146 const struct lttng_directory_handle *handle,
147 const char *subdirectory_path,
148 mode_t mode, const struct lttng_credentials *creds);
151 * Open a file descriptor to a path relative to a directory handle.
153 int lttng_directory_handle_open_file(
154 const struct lttng_directory_handle *handle,
155 const char *filename,
156 int flags, mode_t mode);
159 * Open a file descriptor to a path relative to a directory handle
162 int lttng_directory_handle_open_file_as_user(
163 const struct lttng_directory_handle *handle,
164 const char *filename,
165 int flags, mode_t mode,
166 const struct lttng_credentials *creds);
169 * Unlink a file to a path relative to a directory handle.
171 int lttng_directory_handle_unlink_file(
172 const struct lttng_directory_handle *handle,
173 const char *filename);
176 * Unlink a file to a path relative to a directory handle as a given user.
178 int lttng_directory_handle_unlink_file_as_user(
179 const struct lttng_directory_handle *handle,
180 const char *filename,
181 const struct lttng_credentials *creds);
184 * Rename a file from a path relative to a directory handle to a new
185 * name relative to another directory handle.
187 int lttng_directory_handle_rename(
188 const struct lttng_directory_handle *old_handle,
189 const char *old_name,
190 const struct lttng_directory_handle *new_handle,
191 const char *new_name);
194 * Rename a file from a path relative to a directory handle to a new
195 * name relative to another directory handle as a given user.
197 int lttng_directory_handle_rename_as_user(
198 const struct lttng_directory_handle *old_handle,
199 const char *old_name,
200 const struct lttng_directory_handle *new_handle,
201 const char *new_name,
202 const struct lttng_credentials *creds);
205 * Remove a subdirectory relative to a directory handle.
207 int lttng_directory_handle_remove_subdirectory(
208 const struct lttng_directory_handle *handle,
212 * Remove a subdirectory relative to a directory handle as a given user.
214 int lttng_directory_handle_remove_subdirectory_as_user(
215 const struct lttng_directory_handle *handle,
217 const struct lttng_credentials *creds);
220 * Remove a subdirectory and remove its contents if it only
221 * consists in empty directories.
222 * @flags: enum lttng_directory_handle_rmdir_recursive_flags
224 int lttng_directory_handle_remove_subdirectory_recursive(
225 const struct lttng_directory_handle *handle,
226 const char *name, int flags);
229 * Remove a subdirectory and remove its contents if it only
230 * consists in empty directories as a given user.
231 * @flags: enum lttng_directory_handle_rmdir_recursive_flags
233 int lttng_directory_handle_remove_subdirectory_recursive_as_user(
234 const struct lttng_directory_handle *handle,
236 const struct lttng_credentials *creds,
240 * stat() a file relative to a directory handle.
242 int lttng_directory_handle_stat(
243 const struct lttng_directory_handle *handle,
245 struct stat *stat_buf);
248 * Returns true if this directory handle is backed by a file
249 * descriptor, false otherwise.
251 bool lttng_directory_handle_uses_fd(
252 const struct lttng_directory_handle *handle);
255 * Compare two directory handles.
257 * Returns true if the two directory handles are equal, false otherwise.
259 bool lttng_directory_handle_equals(const struct lttng_directory_handle *lhs,
260 const struct lttng_directory_handle *rhs);
263 #endif /* _COMPAT_PATH_HANDLE_H */