src/common/compat/directory-handle.h

   1 /*
   2  * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com>
   3  *
   4  * SPDX-License-Identifier: GPL-2.0-only
   5  *
   6  */
   7
   8 #ifndef _COMPAT_DIRECTORY_HANDLE_H
   9 #define _COMPAT_DIRECTORY_HANDLE_H
  10
  11 #include <common/credentials.h>
  12 #include <common/macros.h>
  13 #include <sys/stat.h>
  14 #include <urcu/ref.h>
  15
  16 #ifdef __cplusplus
  17 extern "C" {
  18 #endif
  19
  20 enum lttng_directory_handle_rmdir_recursive_flags {
  21         LTTNG_DIRECTORY_HANDLE_FAIL_NON_EMPTY_FLAG = (1U << 0),
  22         LTTNG_DIRECTORY_HANDLE_SKIP_NON_EMPTY_FLAG = (1U << 1),
  23 };
  24
  25 /*
  26  * Some platforms, such as Solaris 10, do not support directory file descriptors
  27  * and their associated functions (*at(...)), which are defined in POSIX.2008.
  28  *
  29  * This wrapper provides a handle that is either a copy of a directory's path
  30  * or a directory file descriptors, depending on the platform's capabilities.
  31  */
  32 #ifdef HAVE_DIRFD
  33
  34 struct lttng_directory_handle;
  35
  36 typedef void (*lttng_directory_handle_destroy_cb)(
  37                 struct lttng_directory_handle *handle, void *data);
  38
  39 struct lttng_directory_handle {
  40         struct urcu_ref ref;
  41         ino_t directory_inode;
  42         int dirfd;
  43         lttng_directory_handle_destroy_cb destroy_cb;
  44         void *destroy_cb_data;
  45 };
  46
  47 static inline
  48 int lttng_directory_handle_get_dirfd(
  49                 const struct lttng_directory_handle *handle)
  50 {
  51         return handle->dirfd;
  52 }
  53
  54 #else
  55 struct lttng_directory_handle {
  56         struct urcu_ref ref;
  57         char *base_path;
  58 };
  59 #endif
  60
  61 /*
  62  * Create a directory handle to the provided path. Passing a NULL path
  63  * returns a handle to the current working directory.
  64  *
  65  * The reference to the directory handle must be released using
  66  * lttng_directory_handle_put().
  67  */
  68 struct lttng_directory_handle *lttng_directory_handle_create(
  69                 const char *path);
  70
  71 /*
  72  * Create a new directory handle to a path relative to an existing handle.
  73  *
  74  * The provided path must already exist. Note that the creation of a
  75  * subdirectory and the creation of a handle are kept as separate operations
  76  * to highlight the fact that there is an inherent race between the creation of
  77  * a directory and the creation of a handle to it.
  78  *
  79  * Passing a NULL path effectively copies the original handle.
  80  *
  81  * The reference to the directory handle must be released using
  82  * lttng_directory_handle_put().
  83  */
  84 struct lttng_directory_handle *lttng_directory_handle_create_from_handle(
  85                 const char *path,
  86                 const struct lttng_directory_handle *ref_handle);
  87
  88 /*
  89  * Create a new directory handle from an existing directory fd.
  90  *
  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.
  94  *
  95  * The reference to the directory handle must be released using
  96  * lttng_directory_handle_put().
  97  */
  98 struct lttng_directory_handle *lttng_directory_handle_create_from_dirfd(
  99                 int dirfd);
 100
 101 /*
 102  * Copy a directory handle.
 103  *
 104  * The reference to the directory handle must be released using
 105  * lttng_directory_handle_put().
 106  */
 107 struct lttng_directory_handle *lttng_directory_handle_copy(
 108                 const struct lttng_directory_handle *handle);
 109
 110 /*
 111  * Acquire a reference to a directory handle.
 112  */
 113 bool lttng_directory_handle_get(struct lttng_directory_handle *handle);
 114
 115 /*
 116  * Release a reference to a directory handle.
 117  */
 118 void lttng_directory_handle_put(struct lttng_directory_handle *handle);
 119
 120 /*
 121  * Create a subdirectory relative to a directory handle.
 122  */
 123 int lttng_directory_handle_create_subdirectory(
 124                 const struct lttng_directory_handle *handle,
 125                 const char *subdirectory,
 126                 mode_t mode);
 127
 128 /*
 129  * Create a subdirectory relative to a directory handle
 130  * as a given user.
 131  */
 132 int lttng_directory_handle_create_subdirectory_as_user(
 133                 const struct lttng_directory_handle *handle,
 134                 const char *subdirectory,
 135                 mode_t mode, const struct lttng_credentials *creds);
 136
 137 /*
 138  * Recursively create a directory relative to a directory handle.
 139  */
 140 int lttng_directory_handle_create_subdirectory_recursive(
 141                 const struct lttng_directory_handle *handle,
 142                 const char *subdirectory_path,
 143                 mode_t mode);
 144
 145 /*
 146  * Recursively create a directory relative to a directory handle
 147  * as a given user.
 148  */
 149 int lttng_directory_handle_create_subdirectory_recursive_as_user(
 150                 const struct lttng_directory_handle *handle,
 151                 const char *subdirectory_path,
 152                 mode_t mode, const struct lttng_credentials *creds);
 153
 154 /*
 155  * Open a file descriptor to a path relative to a directory handle.
 156  */
 157 int lttng_directory_handle_open_file(
 158                 const struct lttng_directory_handle *handle,
 159                 const char *filename,
 160                 int flags, mode_t mode);
 161
 162 /*
 163  * Open a file descriptor to a path relative to a directory handle
 164  * as a given user.
 165  */
 166 int lttng_directory_handle_open_file_as_user(
 167                 const struct lttng_directory_handle *handle,
 168                 const char *filename,
 169                 int flags, mode_t mode,
 170                 const struct lttng_credentials *creds);
 171
 172 /*
 173  * Unlink a file to a path relative to a directory handle.
 174  */
 175 int lttng_directory_handle_unlink_file(
 176                 const struct lttng_directory_handle *handle,
 177                 const char *filename);
 178
 179 /*
 180  * Unlink a file to a path relative to a directory handle as a given user.
 181  */
 182 int lttng_directory_handle_unlink_file_as_user(
 183                 const struct lttng_directory_handle *handle,
 184                 const char *filename,
 185                 const struct lttng_credentials *creds);
 186
 187 /*
 188  * Rename a file from a path relative to a directory handle to a new
 189  * name relative to another directory handle.
 190  */
 191 int lttng_directory_handle_rename(
 192                 const struct lttng_directory_handle *old_handle,
 193                 const char *old_name,
 194                 const struct lttng_directory_handle *new_handle,
 195                 const char *new_name);
 196
 197 /*
 198  * Rename a file from a path relative to a directory handle to a new
 199  * name relative to another directory handle as a given user.
 200  */
 201 int lttng_directory_handle_rename_as_user(
 202                 const struct lttng_directory_handle *old_handle,
 203                 const char *old_name,
 204                 const struct lttng_directory_handle *new_handle,
 205                 const char *new_name,
 206                 const struct lttng_credentials *creds);
 207
 208 /*
 209  * Remove a subdirectory relative to a directory handle.
 210  */
 211 int lttng_directory_handle_remove_subdirectory(
 212                 const struct lttng_directory_handle *handle,
 213                 const char *name);
 214
 215 /*
 216  * Remove a subdirectory relative to a directory handle as a given user.
 217  */
 218 int lttng_directory_handle_remove_subdirectory_as_user(
 219                 const struct lttng_directory_handle *handle,
 220                 const char *name,
 221                 const struct lttng_credentials *creds);
 222
 223 /*
 224  * Remove a subdirectory and remove its contents if it only
 225  * consists in empty directories.
 226  * @flags: enum lttng_directory_handle_rmdir_recursive_flags
 227  */
 228 int lttng_directory_handle_remove_subdirectory_recursive(
 229                 const struct lttng_directory_handle *handle,
 230                 const char *name, int flags);
 231
 232 /*
 233  * Remove a subdirectory and remove its contents if it only
 234  * consists in empty directories as a given user.
 235  * @flags: enum lttng_directory_handle_rmdir_recursive_flags
 236  */
 237 int lttng_directory_handle_remove_subdirectory_recursive_as_user(
 238                 const struct lttng_directory_handle *handle,
 239                 const char *name,
 240                 const struct lttng_credentials *creds,
 241                 int flags);
 242
 243 /*
 244  * stat() a file relative to a directory handle.
 245  */
 246 int lttng_directory_handle_stat(
 247                 const struct lttng_directory_handle *handle,
 248                 const char *name,
 249                 struct stat *stat_buf);
 250
 251 /*
 252  * Returns true if this directory handle is backed by a file
 253  * descriptor, false otherwise.
 254  */
 255 bool lttng_directory_handle_uses_fd(
 256                 const struct lttng_directory_handle *handle);
 257
 258 /*
 259  * Compare two directory handles.
 260  *
 261  * Returns true if the two directory handles are equal, false otherwise.
 262  */
 263 bool lttng_directory_handle_equals(const struct lttng_directory_handle *lhs,
 264                 const struct lttng_directory_handle *rhs);
 265
 266
 267 #ifdef __cplusplus
 268 }
 269 #endif
 270
 271 #endif /* _COMPAT_PATH_HANDLE_H */