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
  24 enum lttng_directory_handle_rmdir_recursive_flags {
  25         LTTNG_DIRECTORY_HANDLE_FAIL_NON_EMPTY_FLAG = (1U << 0),
  26         LTTNG_DIRECTORY_HANDLE_SKIP_NON_EMPTY_FLAG = (1U << 1),
  27 };
  28
  29 /*
  30  * Some platforms, such as Solaris 10, do not support directory file descriptors
  31  * and their associated functions (*at(...)), which are defined in POSIX.2008.
  32  *
  33  * This wrapper provides a handle that is either a copy of a directory's path
  34  * or a directory file descriptors, depending on the platform's capabilities.
  35  */
  36 #ifdef COMPAT_DIRFD
  37 struct lttng_directory_handle {
  38         int dirfd;
  39 };
  40
  41 static inline
  42 int lttng_directory_handle_get_dirfd(
  43                 const struct lttng_directory_handle *handle)
  44 {
  45         return handle->dirfd;
  46 }
  47
  48 #else
  49 struct lttng_directory_handle {
  50         char *base_path;
  51 };
  52 #endif
  53
  54 /*
  55  * Initialize a directory handle to the provided path. Passing a NULL path
  56  * returns a handle to the current working directory.
  57  *
  58  * An initialized directory handle must be finalized using
  59  * lttng_directory_handle_fini().
  60  */
  61 LTTNG_HIDDEN
  62 int lttng_directory_handle_init(struct lttng_directory_handle *handle,
  63                 const char *path);
  64
  65 /*
  66  * Initialize a new directory handle to a path relative to an existing handle.
  67  *
  68  * The provided path must already exist. Note that the creation of a
  69  * subdirectory and the creation of a handle are kept as separate operations
  70  * to highlight the fact that there is an inherent race between the creation of
  71  * a directory and the creation of a handle to it.
  72  *
  73  * Passing a NULL path effectively copies the original handle.
  74  *
  75  * An initialized directory handle must be finalized using
  76  * lttng_directory_handle_fini().
  77  */
  78 LTTNG_HIDDEN
  79 int lttng_directory_handle_init_from_handle(
  80                 struct lttng_directory_handle *new_handle,
  81                 const char *path,
  82                 const struct lttng_directory_handle *handle);
  83
  84 /*
  85  * Initialize a new directory handle from an existing directory fd.
  86  *
  87  * The new directory handle assumes the ownership of the directory fd.
  88  * Note that this method should only be used in very specific cases, such as
  89  * re-creating a directory handle from a dirfd passed over a unix socket.
  90  *
  91  * An initialized directory handle must be finalized using
  92  * lttng_directory_handle_fini().
  93  */
  94 LTTNG_HIDDEN
  95 int lttng_directory_handle_init_from_dirfd(
  96                 struct lttng_directory_handle *handle, int dirfd);
  97
  98 /*
  99  * Copy a directory handle.
 100  */
 101 LTTNG_HIDDEN
 102 int lttng_directory_handle_copy(const struct lttng_directory_handle *handle,
 103                 struct lttng_directory_handle *new_copy);
 104
 105 /*
 106  * Move a directory handle. The original directory handle may no longer be
 107  * used after this call. This call cannot fail; directly assign the
 108  * return value to the new directory handle.
 109  *
 110  * It is safe (but unnecessary) to call lttng_directory_handle_fini on the
 111  * original handle.
 112  */
 113 LTTNG_HIDDEN
 114 struct lttng_directory_handle
 115 lttng_directory_handle_move(struct lttng_directory_handle *original);
 116
 117 /*
 118  * Release the resources of a directory handle.
 119  */
 120 LTTNG_HIDDEN
 121 void lttng_directory_handle_fini(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 #endif /* _COMPAT_PATH_HANDLE_H */