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/credentials.h>
22 #include <common/macros.h>
26 enum lttng_directory_handle_rmdir_recursive_flags
{
27 LTTNG_DIRECTORY_HANDLE_FAIL_NON_EMPTY_FLAG
= (1U << 0),
28 LTTNG_DIRECTORY_HANDLE_SKIP_NON_EMPTY_FLAG
= (1U << 1),
32 * Some platforms, such as Solaris 10, do not support directory file descriptors
33 * and their associated functions (*at(...)), which are defined in POSIX.2008.
35 * This wrapper provides a handle that is either a copy of a directory's path
36 * or a directory file descriptors, depending on the platform's capabilities.
39 struct lttng_directory_handle
{
41 ino_t directory_inode
;
46 int lttng_directory_handle_get_dirfd(
47 const struct lttng_directory_handle
*handle
)
53 struct lttng_directory_handle
{
60 * Create a directory handle to the provided path. Passing a NULL path
61 * returns a handle to the current working directory.
63 * The reference to the directory handle must be released using
64 * lttng_directory_handle_put().
67 struct lttng_directory_handle
*lttng_directory_handle_create(
71 * Create a new directory handle to a path relative to an existing handle.
73 * The provided path must already exist. Note that the creation of a
74 * subdirectory and the creation of a handle are kept as separate operations
75 * to highlight the fact that there is an inherent race between the creation of
76 * a directory and the creation of a handle to it.
78 * Passing a NULL path effectively copies the original handle.
80 * The reference to the directory handle must be released using
81 * lttng_directory_handle_put().
84 struct lttng_directory_handle
*lttng_directory_handle_create_from_handle(
86 const struct lttng_directory_handle
*ref_handle
);
89 * Create a new directory handle from an existing directory fd.
91 * The new directory handle assumes the ownership of the directory fd.
92 * Note that this method should only be used in very specific cases, such as
93 * re-creating a directory handle from a dirfd passed over a unix socket.
95 * The reference to the directory handle must be released using
96 * lttng_directory_handle_put().
99 struct lttng_directory_handle
*lttng_directory_handle_create_from_dirfd(
103 * Copy a directory handle.
105 * The reference to the directory handle must be released using
106 * lttng_directory_handle_put().
109 struct lttng_directory_handle
*lttng_directory_handle_copy(
110 const struct lttng_directory_handle
*handle
);
113 * Acquire a reference to a directory handle.
116 bool lttng_directory_handle_get(struct lttng_directory_handle
*handle
);
119 * Release a reference to a directory handle.
122 void lttng_directory_handle_put(struct lttng_directory_handle
*handle
);
125 * Create a subdirectory relative to a directory handle.
128 int lttng_directory_handle_create_subdirectory(
129 const struct lttng_directory_handle
*handle
,
130 const char *subdirectory
,
134 * Create a subdirectory relative to a directory handle
138 int lttng_directory_handle_create_subdirectory_as_user(
139 const struct lttng_directory_handle
*handle
,
140 const char *subdirectory
,
141 mode_t mode
, const struct lttng_credentials
*creds
);
144 * Recursively create a directory relative to a directory handle.
147 int lttng_directory_handle_create_subdirectory_recursive(
148 const struct lttng_directory_handle
*handle
,
149 const char *subdirectory_path
,
153 * Recursively create a directory relative to a directory handle
157 int lttng_directory_handle_create_subdirectory_recursive_as_user(
158 const struct lttng_directory_handle
*handle
,
159 const char *subdirectory_path
,
160 mode_t mode
, const struct lttng_credentials
*creds
);
163 * Open a file descriptor to a path relative to a directory handle.
166 int lttng_directory_handle_open_file(
167 const struct lttng_directory_handle
*handle
,
168 const char *filename
,
169 int flags
, mode_t mode
);
172 * Open a file descriptor to a path relative to a directory handle
176 int lttng_directory_handle_open_file_as_user(
177 const struct lttng_directory_handle
*handle
,
178 const char *filename
,
179 int flags
, mode_t mode
,
180 const struct lttng_credentials
*creds
);
183 * Unlink a file to a path relative to a directory handle.
186 int lttng_directory_handle_unlink_file(
187 const struct lttng_directory_handle
*handle
,
188 const char *filename
);
191 * Unlink a file to a path relative to a directory handle as a given user.
194 int lttng_directory_handle_unlink_file_as_user(
195 const struct lttng_directory_handle
*handle
,
196 const char *filename
,
197 const struct lttng_credentials
*creds
);
200 * Rename a file from a path relative to a directory handle to a new
201 * name relative to another directory handle.
204 int lttng_directory_handle_rename(
205 const struct lttng_directory_handle
*old_handle
,
206 const char *old_name
,
207 const struct lttng_directory_handle
*new_handle
,
208 const char *new_name
);
211 * Rename a file from a path relative to a directory handle to a new
212 * name relative to another directory handle as a given user.
215 int lttng_directory_handle_rename_as_user(
216 const struct lttng_directory_handle
*old_handle
,
217 const char *old_name
,
218 const struct lttng_directory_handle
*new_handle
,
219 const char *new_name
,
220 const struct lttng_credentials
*creds
);
223 * Remove a subdirectory relative to a directory handle.
226 int lttng_directory_handle_remove_subdirectory(
227 const struct lttng_directory_handle
*handle
,
231 * Remove a subdirectory relative to a directory handle as a given user.
234 int lttng_directory_handle_remove_subdirectory_as_user(
235 const struct lttng_directory_handle
*handle
,
237 const struct lttng_credentials
*creds
);
240 * Remove a subdirectory and remove its contents if it only
241 * consists in empty directories.
242 * @flags: enum lttng_directory_handle_rmdir_recursive_flags
245 int lttng_directory_handle_remove_subdirectory_recursive(
246 const struct lttng_directory_handle
*handle
,
247 const char *name
, int flags
);
250 * Remove a subdirectory and remove its contents if it only
251 * consists in empty directories as a given user.
252 * @flags: enum lttng_directory_handle_rmdir_recursive_flags
255 int lttng_directory_handle_remove_subdirectory_recursive_as_user(
256 const struct lttng_directory_handle
*handle
,
258 const struct lttng_credentials
*creds
,
262 * stat() a file relative to a directory handle.
265 int lttng_directory_handle_stat(
266 const struct lttng_directory_handle
*handle
,
268 struct stat
*stat_buf
);
271 * Returns true if this directory handle is backed by a file
272 * descriptor, false otherwise.
275 bool lttng_directory_handle_uses_fd(
276 const struct lttng_directory_handle
*handle
);
279 * Compare two directory handles.
281 * Returns true if the two directory handles are equal, false otherwise.
284 bool lttng_directory_handle_equals(const struct lttng_directory_handle
*lhs
,
285 const struct lttng_directory_handle
*rhs
);
287 #endif /* _COMPAT_PATH_HANDLE_H */