ceph/src/pmdk/src/include/libpmempool.h

   1 /* SPDX-License-Identifier: BSD-3-Clause */
   2 /* Copyright 2016-2020, Intel Corporation */
   3
   4 /*
   5  * libpmempool.h -- definitions of libpmempool entry points
   6  *
   7  * See libpmempool(7) for details.
   8  */
   9
  10 #ifndef LIBPMEMPOOL_H
  11 #define LIBPMEMPOOL_H 1
  12
  13 #include <stdint.h>
  14 #include <stddef.h>
  15 #include <limits.h>
  16
  17 #ifdef _WIN32
  18 #include <pmemcompat.h>
  19
  20 #ifndef PMDK_UTF8_API
  21 #define pmempool_check_status pmempool_check_statusW
  22 #define pmempool_check_args pmempool_check_argsW
  23
  24 #define pmempool_check_init pmempool_check_initW
  25 #define pmempool_check pmempool_checkW
  26 #define pmempool_sync pmempool_syncW
  27 #define pmempool_transform pmempool_transformW
  28 #define pmempool_rm pmempool_rmW
  29 #define pmempool_check_version pmempool_check_versionW
  30 #define pmempool_errormsg pmempool_errormsgW
  31 #define pmempool_feature_enable pmempool_feature_enableW
  32 #define pmempool_feature_disable pmempool_feature_disableW
  33 #define pmempool_feature_query pmempool_feature_queryW
  34 #else
  35 #define pmempool_check_status pmempool_check_statusU
  36 #define pmempool_check_args pmempool_check_argsU
  37
  38 #define pmempool_check_init pmempool_check_initU
  39 #define pmempool_check pmempool_checkU
  40 #define pmempool_sync pmempool_syncU
  41 #define pmempool_transform pmempool_transformU
  42 #define pmempool_rm pmempool_rmU
  43 #define pmempool_check_version pmempool_check_versionU
  44 #define pmempool_errormsg pmempool_errormsgU
  45 #define pmempool_feature_enable pmempool_feature_enableU
  46 #define pmempool_feature_disable pmempool_feature_disableU
  47 #define pmempool_feature_query pmempool_feature_queryU
  48 #endif
  49
  50 #endif
  51
  52 #ifdef __cplusplus
  53 extern "C" {
  54 #endif
  55
  56 /* PMEMPOOL CHECK */
  57
  58 /*
  59  * pool types
  60  */
  61 enum pmempool_pool_type {
  62         PMEMPOOL_POOL_TYPE_DETECT,
  63         PMEMPOOL_POOL_TYPE_LOG,
  64         PMEMPOOL_POOL_TYPE_BLK,
  65         PMEMPOOL_POOL_TYPE_OBJ,
  66         PMEMPOOL_POOL_TYPE_BTT,
  67         PMEMPOOL_POOL_TYPE_RESERVED1, /* used to be cto */
  68 };
  69
  70 /*
  71  * perform repairs
  72  */
  73 #define PMEMPOOL_CHECK_REPAIR           (1U << 0)
  74 /*
  75  * emulate repairs
  76  */
  77 #define PMEMPOOL_CHECK_DRY_RUN          (1U << 1)
  78 /*
  79  * perform hazardous repairs
  80  */
  81 #define PMEMPOOL_CHECK_ADVANCED         (1U << 2)
  82 /*
  83  * do not ask before repairs
  84  */
  85 #define PMEMPOOL_CHECK_ALWAYS_YES       (1U << 3)
  86 /*
  87  * generate info statuses
  88  */
  89 #define PMEMPOOL_CHECK_VERBOSE          (1U << 4)
  90 /*
  91  * generate string format statuses
  92  */
  93 #define PMEMPOOL_CHECK_FORMAT_STR       (1U << 5)
  94
  95 /*
  96  * types of check statuses
  97  */
  98 enum pmempool_check_msg_type {
  99         PMEMPOOL_CHECK_MSG_TYPE_INFO,
 100         PMEMPOOL_CHECK_MSG_TYPE_ERROR,
 101         PMEMPOOL_CHECK_MSG_TYPE_QUESTION,
 102 };
 103
 104 /*
 105  * check result types
 106  */
 107 enum pmempool_check_result {
 108         PMEMPOOL_CHECK_RESULT_CONSISTENT,
 109         PMEMPOOL_CHECK_RESULT_NOT_CONSISTENT,
 110         PMEMPOOL_CHECK_RESULT_REPAIRED,
 111         PMEMPOOL_CHECK_RESULT_CANNOT_REPAIR,
 112         PMEMPOOL_CHECK_RESULT_ERROR,
 113         PMEMPOOL_CHECK_RESULT_SYNC_REQ,
 114 };
 115
 116 /*
 117  * check context
 118  */
 119 typedef struct pmempool_check_ctx PMEMpoolcheck;
 120
 121 /*
 122  * finalize the check and get the result
 123  */
 124 enum pmempool_check_result pmempool_check_end(PMEMpoolcheck *ppc);
 125
 126 /* PMEMPOOL RM */
 127
 128 #define PMEMPOOL_RM_FORCE               (1U << 0) /* ignore any errors */
 129 #define PMEMPOOL_RM_POOLSET_LOCAL       (1U << 1) /* remove local poolsets */
 130 #define PMEMPOOL_RM_POOLSET_REMOTE      (1U << 2) /* remove remote poolsets */
 131
 132 /*
 133  * LIBPMEMPOOL SYNC
 134  */
 135
 136 /*
 137  * fix bad blocks - it requires creating or reading special recovery files
 138  */
 139 #define PMEMPOOL_SYNC_FIX_BAD_BLOCKS    (1U << 0)
 140 /*
 141  * do not apply changes, only check if operation is viable
 142  */
 143 #define PMEMPOOL_SYNC_DRY_RUN           (1U << 1)
 144
 145 /*
 146  * LIBPMEMPOOL TRANSFORM
 147  */
 148
 149 /*
 150  * do not apply changes, only check if operation is viable
 151  */
 152 #define PMEMPOOL_TRANSFORM_DRY_RUN      (1U << 1)
 153
 154 /*
 155  * PMEMPOOL_MAJOR_VERSION and PMEMPOOL_MINOR_VERSION provide the current version
 156  * of the libpmempool API as provided by this header file.  Applications can
 157  * verify that the version available at run-time is compatible with the version
 158  * used at compile-time by passing these defines to pmempool_check_version().
 159  */
 160 #define PMEMPOOL_MAJOR_VERSION 1
 161 #define PMEMPOOL_MINOR_VERSION 3
 162
 163 /*
 164  * check status
 165  */
 166 struct pmempool_check_statusU {
 167         enum pmempool_check_msg_type type;
 168         struct {
 169                 const char *msg;
 170                 const char *answer;
 171         } str;
 172 };
 173
 174 #ifndef _WIN32
 175 #define pmempool_check_status pmempool_check_statusU
 176 #else
 177 struct pmempool_check_statusW {
 178         enum pmempool_check_msg_type type;
 179         struct {
 180                 const wchar_t *msg;
 181                 const wchar_t *answer;
 182         } str;
 183 };
 184 #endif
 185
 186 /*
 187  * check context arguments
 188  */
 189 struct pmempool_check_argsU {
 190         const char *path;
 191         const char *backup_path;
 192         enum pmempool_pool_type pool_type;
 193         unsigned flags;
 194 };
 195
 196 #ifndef _WIN32
 197 #define pmempool_check_args pmempool_check_argsU
 198 #else
 199 struct pmempool_check_argsW {
 200         const wchar_t *path;
 201         const wchar_t *backup_path;
 202         enum pmempool_pool_type pool_type;
 203         unsigned flags;
 204 };
 205 #endif
 206
 207 /*
 208  * initialize a check context
 209  */
 210 #ifndef _WIN32
 211 PMEMpoolcheck *
 212 pmempool_check_init(struct pmempool_check_args *args, size_t args_size);
 213 #else
 214 PMEMpoolcheck *
 215 pmempool_check_initU(struct pmempool_check_argsU *args, size_t args_size);
 216 PMEMpoolcheck *
 217 pmempool_check_initW(struct pmempool_check_argsW *args, size_t args_size);
 218 #endif
 219
 220 /*
 221  * start / resume the check
 222  */
 223 #ifndef _WIN32
 224 struct pmempool_check_status *pmempool_check(PMEMpoolcheck *ppc);
 225 #else
 226 struct pmempool_check_statusU *pmempool_checkU(PMEMpoolcheck *ppc);
 227 struct pmempool_check_statusW *pmempool_checkW(PMEMpoolcheck *ppc);
 228 #endif
 229
 230 /*
 231  * LIBPMEMPOOL SYNC & TRANSFORM
 232  */
 233
 234 /*
 235  * Synchronize data between replicas within a poolset.
 236  *
 237  * EXPERIMENTAL
 238  */
 239 #ifndef _WIN32
 240 int pmempool_sync(const char *poolset_file, unsigned flags);
 241 #else
 242 int pmempool_syncU(const char *poolset_file, unsigned flags);
 243 int pmempool_syncW(const wchar_t *poolset_file, unsigned flags);
 244 #endif
 245
 246 /*
 247  * Modify internal structure of a poolset.
 248  *
 249  * EXPERIMENTAL
 250  */
 251 #ifndef _WIN32
 252 int pmempool_transform(const char *poolset_file_src,
 253         const char *poolset_file_dst, unsigned flags);
 254 #else
 255 int pmempool_transformU(const char *poolset_file_src,
 256         const char *poolset_file_dst, unsigned flags);
 257 int pmempool_transformW(const wchar_t *poolset_file_src,
 258         const wchar_t *poolset_file_dst, unsigned flags);
 259 #endif
 260
 261 /* PMEMPOOL feature enable, disable, query */
 262
 263 /*
 264  * feature types
 265  */
 266 enum pmempool_feature {
 267         PMEMPOOL_FEAT_SINGLEHDR,
 268         PMEMPOOL_FEAT_CKSUM_2K,
 269         PMEMPOOL_FEAT_SHUTDOWN_STATE,
 270         PMEMPOOL_FEAT_CHECK_BAD_BLOCKS,
 271 };
 272
 273 /* PMEMPOOL FEATURE ENABLE */
 274 #ifndef _WIN32
 275 int pmempool_feature_enable(const char *path, enum pmempool_feature feature,
 276         unsigned flags);
 277 #else
 278 int pmempool_feature_enableU(const char *path, enum pmempool_feature feature,
 279         unsigned flags);
 280 int pmempool_feature_enableW(const wchar_t *path,
 281         enum pmempool_feature feature, unsigned flags);
 282 #endif
 283
 284 /* PMEMPOOL FEATURE DISABLE */
 285 #ifndef _WIN32
 286 int pmempool_feature_disable(const char *path, enum pmempool_feature feature,
 287         unsigned flags);
 288 #else
 289 int pmempool_feature_disableU(const char *path, enum pmempool_feature feature,
 290         unsigned flags);
 291 int pmempool_feature_disableW(const wchar_t *path,
 292         enum pmempool_feature feature, unsigned flags);
 293 #endif
 294
 295 /* PMEMPOOL FEATURE QUERY */
 296 #ifndef _WIN32
 297 int pmempool_feature_query(const char *path, enum pmempool_feature feature,
 298         unsigned flags);
 299 #else
 300 int pmempool_feature_queryU(const char *path, enum pmempool_feature feature,
 301         unsigned flags);
 302 int pmempool_feature_queryW(const wchar_t *path,
 303         enum pmempool_feature feature, unsigned flags);
 304 #endif
 305
 306 /* PMEMPOOL RM */
 307 #ifndef _WIN32
 308 int pmempool_rm(const char *path, unsigned flags);
 309 #else
 310 int pmempool_rmU(const char *path, unsigned flags);
 311 int pmempool_rmW(const wchar_t *path, unsigned flags);
 312 #endif
 313
 314 #ifndef _WIN32
 315 const char *pmempool_check_version(unsigned major_required,
 316         unsigned minor_required);
 317 #else
 318 const char *pmempool_check_versionU(unsigned major_required,
 319         unsigned minor_required);
 320 const wchar_t *pmempool_check_versionW(unsigned major_required,
 321         unsigned minor_required);
 322 #endif
 323
 324 #ifndef _WIN32
 325 const char *pmempool_errormsg(void);
 326 #else
 327 const char *pmempool_errormsgU(void);
 328 const wchar_t *pmempool_errormsgW(void);
 329 #endif
 330
 331 #ifdef __cplusplus
 332 }
 333 #endif
 334 #endif  /* libpmempool.h */