src/common/compat/directory-handle.hpp

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