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.h>
12 #include <common/macros.h>
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 */