src/common/compat/directory-handle.h

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