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 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),
  19 };
  20
  21 /*
  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.
  24  *
  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.
  27  */
  28 #ifdef COMPAT_DIRFD
  29 struct lttng_directory_handle {
  30         struct urcu_ref ref;
  31         ino_t directory_inode;
  32         int dirfd;
  33 };
  34
  35 static inline
  36 int lttng_directory_handle_get_dirfd(
  37                 const struct lttng_directory_handle *handle)
  38 {
  39         return handle->dirfd;
  40 }
  41
  42 #else
  43 struct lttng_directory_handle {
  44         struct urcu_ref ref;
  45         char *base_path;
  46 };
  47 #endif
  48
  49 /*
  50  * Create a directory handle to the provided path. Passing a NULL path
  51  * returns a handle to the current working directory.
  52  *
  53  * The reference to the directory handle must be released using
  54  * lttng_directory_handle_put().
  55  */
  56 LTTNG_HIDDEN
  57 struct lttng_directory_handle *lttng_directory_handle_create(
  58                 const char *path);
  59
  60 /*
  61  * Create a new directory handle to a path relative to an existing handle.
  62  *
  63  * The provided path must already exist. Note that the creation of a
  64  * subdirectory and the creation of a handle are kept as separate operations
  65  * to highlight the fact that there is an inherent race between the creation of
  66  * a directory and the creation of a handle to it.
  67  *
  68  * Passing a NULL path effectively copies the original handle.
  69  *
  70  * The reference to the directory handle must be released using
  71  * lttng_directory_handle_put().
  72  */
  73 LTTNG_HIDDEN
  74 struct lttng_directory_handle *lttng_directory_handle_create_from_handle(
  75                 const char *path,
  76                 const struct lttng_directory_handle *ref_handle);
  77
  78 /*
  79  * Create a new directory handle from an existing directory fd.
  80  *
  81  * The new directory handle assumes the ownership of the directory fd.
  82  * Note that this method should only be used in very specific cases, such as
  83  * re-creating a directory handle from a dirfd passed over a unix socket.
  84  *
  85  * The reference to the directory handle must be released using
  86  * lttng_directory_handle_put().
  87  */
  88 LTTNG_HIDDEN
  89 struct lttng_directory_handle *lttng_directory_handle_create_from_dirfd(
  90                 int dirfd);
  91
  92 /*
  93  * Copy a directory handle.
  94  *
  95  * The reference to the directory handle must be released using
  96  * lttng_directory_handle_put().
  97  */
  98 LTTNG_HIDDEN
  99 struct lttng_directory_handle *lttng_directory_handle_copy(
 100                 const struct lttng_directory_handle *handle);
 101
 102 /*
 103  * Acquire a reference to a directory handle.
 104  */
 105 LTTNG_HIDDEN
 106 bool lttng_directory_handle_get(struct lttng_directory_handle *handle);
 107
 108 /*
 109  * Release a reference to a directory handle.
 110  */
 111 LTTNG_HIDDEN
 112 void lttng_directory_handle_put(struct lttng_directory_handle *handle);
 113
 114 /*
 115  * Create a subdirectory relative to a directory handle.
 116  */
 117 LTTNG_HIDDEN
 118 int lttng_directory_handle_create_subdirectory(
 119                 const struct lttng_directory_handle *handle,
 120                 const char *subdirectory,
 121                 mode_t mode);
 122
 123 /*
 124  * Create a subdirectory relative to a directory handle
 125  * as a given user.
 126  */
 127 LTTNG_HIDDEN
 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);
 132
 133 /*
 134  * Recursively create a directory relative to a directory handle.
 135  */
 136 LTTNG_HIDDEN
 137 int lttng_directory_handle_create_subdirectory_recursive(
 138                 const struct lttng_directory_handle *handle,
 139                 const char *subdirectory_path,
 140                 mode_t mode);
 141
 142 /*
 143  * Recursively create a directory relative to a directory handle
 144  * as a given user.
 145  */
 146 LTTNG_HIDDEN
 147 int lttng_directory_handle_create_subdirectory_recursive_as_user(
 148                 const struct lttng_directory_handle *handle,
 149                 const char *subdirectory_path,
 150                 mode_t mode, const struct lttng_credentials *creds);
 151
 152 /*
 153  * Open a file descriptor to a path relative to a directory handle.
 154  */
 155 LTTNG_HIDDEN
 156 int lttng_directory_handle_open_file(
 157                 const struct lttng_directory_handle *handle,
 158                 const char *filename,
 159                 int flags, mode_t mode);
 160
 161 /*
 162  * Open a file descriptor to a path relative to a directory handle
 163  * as a given user.
 164  */
 165 LTTNG_HIDDEN
 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 LTTNG_HIDDEN
 176 int lttng_directory_handle_unlink_file(
 177                 const struct lttng_directory_handle *handle,
 178                 const char *filename);
 179
 180 /*
 181  * Unlink a file to a path relative to a directory handle as a given user.
 182  */
 183 LTTNG_HIDDEN
 184 int lttng_directory_handle_unlink_file_as_user(
 185                 const struct lttng_directory_handle *handle,
 186                 const char *filename,
 187                 const struct lttng_credentials *creds);
 188
 189 /*
 190  * Rename a file from a path relative to a directory handle to a new
 191  * name relative to another directory handle.
 192  */
 193 LTTNG_HIDDEN
 194 int lttng_directory_handle_rename(
 195                 const struct lttng_directory_handle *old_handle,
 196                 const char *old_name,
 197                 const struct lttng_directory_handle *new_handle,
 198                 const char *new_name);
 199
 200 /*
 201  * Rename a file from a path relative to a directory handle to a new
 202  * name relative to another directory handle as a given user.
 203  */
 204 LTTNG_HIDDEN
 205 int lttng_directory_handle_rename_as_user(
 206                 const struct lttng_directory_handle *old_handle,
 207                 const char *old_name,
 208                 const struct lttng_directory_handle *new_handle,
 209                 const char *new_name,
 210                 const struct lttng_credentials *creds);
 211
 212 /*
 213  * Remove a subdirectory relative to a directory handle.
 214  */
 215 LTTNG_HIDDEN
 216 int lttng_directory_handle_remove_subdirectory(
 217                 const struct lttng_directory_handle *handle,
 218                 const char *name);
 219
 220 /*
 221  * Remove a subdirectory relative to a directory handle as a given user.
 222  */
 223 LTTNG_HIDDEN
 224 int lttng_directory_handle_remove_subdirectory_as_user(
 225                 const struct lttng_directory_handle *handle,
 226                 const char *name,
 227                 const struct lttng_credentials *creds);
 228
 229 /*
 230  * Remove a subdirectory and remove its contents if it only
 231  * consists in empty directories.
 232  * @flags: enum lttng_directory_handle_rmdir_recursive_flags
 233  */
 234 LTTNG_HIDDEN
 235 int lttng_directory_handle_remove_subdirectory_recursive(
 236                 const struct lttng_directory_handle *handle,
 237                 const char *name, int flags);
 238
 239 /*
 240  * Remove a subdirectory and remove its contents if it only
 241  * consists in empty directories as a given user.
 242  * @flags: enum lttng_directory_handle_rmdir_recursive_flags
 243  */
 244 LTTNG_HIDDEN
 245 int lttng_directory_handle_remove_subdirectory_recursive_as_user(
 246                 const struct lttng_directory_handle *handle,
 247                 const char *name,
 248                 const struct lttng_credentials *creds,
 249                 int flags);
 250
 251 /*
 252  * stat() a file relative to a directory handle.
 253  */
 254 LTTNG_HIDDEN
 255 int lttng_directory_handle_stat(
 256                 const struct lttng_directory_handle *handle,
 257                 const char *name,
 258                 struct stat *stat_buf);
 259
 260 /*
 261  * Returns true if this directory handle is backed by a file
 262  * descriptor, false otherwise.
 263  */
 264 LTTNG_HIDDEN
 265 bool lttng_directory_handle_uses_fd(
 266                 const struct lttng_directory_handle *handle);
 267
 268 /*
 269  * Compare two directory handles.
 270  *
 271  * Returns true if the two directory handles are equal, false otherwise.
 272  */
 273 LTTNG_HIDDEN
 274 bool lttng_directory_handle_equals(const struct lttng_directory_handle *lhs,
 275                 const struct lttng_directory_handle *rhs);
 276
 277 #endif /* _COMPAT_PATH_HANDLE_H */