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