2 * Copyright (C) 2019 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License, version 2 only,
6 * as published by the Free Software Foundation.
8 * This program is distributed in the hope that it will be useful, but WITHOUT
9 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
10 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
13 * You should have received a copy of the GNU General Public License along
14 * with this program; if not, write to the Free Software Foundation, Inc.,
15 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
18 #ifndef _COMPAT_DIRECTORY_HANDLE_H
19 #define _COMPAT_DIRECTORY_HANDLE_H
21 #include <common/macros.h>
22 #include <common/credentials.h>
25 enum lttng_directory_handle_rmdir_recursive_flags
{
26 LTTNG_DIRECTORY_HANDLE_FAIL_NON_EMPTY_FLAG
= (1U << 0),
27 LTTNG_DIRECTORY_HANDLE_SKIP_NON_EMPTY_FLAG
= (1U << 1),
31 * Some platforms, such as Solaris 10, do not support directory file descriptors
32 * and their associated functions (*at(...)), which are defined in POSIX.2008.
34 * This wrapper provides a handle that is either a copy of a directory's path
35 * or a directory file descriptors, depending on the platform's capabilities.
38 struct lttng_directory_handle
{
40 ino_t directory_inode
;
45 int lttng_directory_handle_get_dirfd(
46 const struct lttng_directory_handle
*handle
)
52 struct lttng_directory_handle
{
59 * Create a directory handle to the provided path. Passing a NULL path
60 * returns a handle to the current working directory.
62 * The reference to the directory handle must be released using
63 * lttng_directory_handle_put().
66 struct lttng_directory_handle
*lttng_directory_handle_create(
70 * Create a new directory handle to a path relative to an existing handle.
72 * The provided path must already exist. Note that the creation of a
73 * subdirectory and the creation of a handle are kept as separate operations
74 * to highlight the fact that there is an inherent race between the creation of
75 * a directory and the creation of a handle to it.
77 * Passing a NULL path effectively copies the original handle.
79 * The reference to the directory handle must be released using
80 * lttng_directory_handle_put().
83 struct lttng_directory_handle
*lttng_directory_handle_create_from_handle(
85 const struct lttng_directory_handle
*ref_handle
);
88 * Create a new directory handle from an existing directory fd.
90 * The new directory handle assumes the ownership of the directory fd.
91 * Note that this method should only be used in very specific cases, such as
92 * re-creating a directory handle from a dirfd passed over a unix socket.
94 * The reference to the directory handle must be released using
95 * lttng_directory_handle_put().
98 struct lttng_directory_handle
*lttng_directory_handle_create_from_dirfd(
102 * Copy a directory handle.
104 * The reference to the directory handle must be released using
105 * lttng_directory_handle_put().
108 struct lttng_directory_handle
*lttng_directory_handle_copy(
109 const struct lttng_directory_handle
*handle
);
112 * Acquire a reference to a directory handle.
115 bool lttng_directory_handle_get(struct lttng_directory_handle
*handle
);
118 * Release a reference to a directory handle.
121 void lttng_directory_handle_put(struct lttng_directory_handle
*handle
);
124 * Create a subdirectory relative to a directory handle.
127 int lttng_directory_handle_create_subdirectory(
128 const struct lttng_directory_handle
*handle
,
129 const char *subdirectory
,
133 * Create a subdirectory relative to a directory handle
137 int lttng_directory_handle_create_subdirectory_as_user(
138 const struct lttng_directory_handle
*handle
,
139 const char *subdirectory
,
140 mode_t mode
, const struct lttng_credentials
*creds
);
143 * Recursively create a directory relative to a directory handle.
146 int lttng_directory_handle_create_subdirectory_recursive(
147 const struct lttng_directory_handle
*handle
,
148 const char *subdirectory_path
,
152 * Recursively create a directory relative to a directory handle
156 int lttng_directory_handle_create_subdirectory_recursive_as_user(
157 const struct lttng_directory_handle
*handle
,
158 const char *subdirectory_path
,
159 mode_t mode
, const struct lttng_credentials
*creds
);
162 * Open a file descriptor to a path relative to a directory handle.
165 int lttng_directory_handle_open_file(
166 const struct lttng_directory_handle
*handle
,
167 const char *filename
,
168 int flags
, mode_t mode
);
171 * Open a file descriptor to a path relative to a directory handle
175 int lttng_directory_handle_open_file_as_user(
176 const struct lttng_directory_handle
*handle
,
177 const char *filename
,
178 int flags
, mode_t mode
,
179 const struct lttng_credentials
*creds
);
182 * Unlink a file to a path relative to a directory handle.
185 int lttng_directory_handle_unlink_file(
186 const struct lttng_directory_handle
*handle
,
187 const char *filename
);
190 * Unlink a file to a path relative to a directory handle as a given user.
193 int lttng_directory_handle_unlink_file_as_user(
194 const struct lttng_directory_handle
*handle
,
195 const char *filename
,
196 const struct lttng_credentials
*creds
);
199 * Rename a file from a path relative to a directory handle to a new
200 * name relative to another directory handle.
203 int lttng_directory_handle_rename(
204 const struct lttng_directory_handle
*old_handle
,
205 const char *old_name
,
206 const struct lttng_directory_handle
*new_handle
,
207 const char *new_name
);
210 * Rename a file from a path relative to a directory handle to a new
211 * name relative to another directory handle as a given user.
214 int lttng_directory_handle_rename_as_user(
215 const struct lttng_directory_handle
*old_handle
,
216 const char *old_name
,
217 const struct lttng_directory_handle
*new_handle
,
218 const char *new_name
,
219 const struct lttng_credentials
*creds
);
222 * Remove a subdirectory relative to a directory handle.
225 int lttng_directory_handle_remove_subdirectory(
226 const struct lttng_directory_handle
*handle
,
230 * Remove a subdirectory relative to a directory handle as a given user.
233 int lttng_directory_handle_remove_subdirectory_as_user(
234 const struct lttng_directory_handle
*handle
,
236 const struct lttng_credentials
*creds
);
239 * Remove a subdirectory and remove its contents if it only
240 * consists in empty directories.
241 * @flags: enum lttng_directory_handle_rmdir_recursive_flags
244 int lttng_directory_handle_remove_subdirectory_recursive(
245 const struct lttng_directory_handle
*handle
,
246 const char *name
, int flags
);
249 * Remove a subdirectory and remove its contents if it only
250 * consists in empty directories as a given user.
251 * @flags: enum lttng_directory_handle_rmdir_recursive_flags
254 int lttng_directory_handle_remove_subdirectory_recursive_as_user(
255 const struct lttng_directory_handle
*handle
,
257 const struct lttng_credentials
*creds
,
261 * Compare two directory handles.
263 * Returns true if the two directory handles are equal, false otherwise.
266 bool lttng_directory_handle_equals(const struct lttng_directory_handle
*lhs
,
267 const struct lttng_directory_handle
*rhs
);
269 #endif /* _COMPAT_PATH_HANDLE_H */