contrib/lvm2/dist/libdm/libdevmapper.h

   1 /*      $NetBSD: libdevmapper.h,v 1.1.1.2 2009/12/02 00:26:09 haad Exp $        */
   2
   3 /*
   4  * Copyright (C) 2001-2004 Sistina Software, Inc. All rights reserved.
   5  * Copyright (C) 2004-2007 Red Hat, Inc. All rights reserved.
   6  *
   7  * This file is part of the device-mapper userspace tools.
   8  *
   9  * This copyrighted material is made available to anyone wishing to use,
  10  * modify, copy, or redistribute it subject to the terms and conditions
  11  * of the GNU Lesser General Public License v.2.1.
  12  *
  13  * You should have received a copy of the GNU Lesser General Public License
  14  * along with this program; if not, write to the Free Software Foundation,
  15  * Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  16  */
  17
  18 #ifndef LIB_DEVICE_MAPPER_H
  19 #define LIB_DEVICE_MAPPER_H
  20
  21 #include <inttypes.h>
  22 #include <stdarg.h>
  23 #include <sys/types.h>
  24
  25 #ifdef linux
  26 #  include <linux/types.h>
  27 #endif
  28
  29 #include <limits.h>
  30 #include <string.h>
  31 #include <stdlib.h>
  32 #include <stdio.h>
  33
  34 /*****************************************************************
  35  * The first section of this file provides direct access to the
  36  * individual device-mapper ioctls.  Since it is quite laborious to
  37  * build the ioctl arguments for the device-mapper, people are
  38  * encouraged to use this library.
  39  ****************************************************************/
  40
  41 /*
  42  * The library user may wish to register their own
  43  * logging function.  By default errors go to stderr.
  44  * Use dm_log_with_errno_init(NULL) to restore the default log fn.
  45  */
  46
  47 typedef void (*dm_log_with_errno_fn) (int level, const char *file, int line,
  48                                       int dm_errno, const char *f, ...)
  49     __attribute__ ((format(printf, 5, 6)));
  50
  51 void dm_log_with_errno_init(dm_log_with_errno_fn fn);
  52 void dm_log_init_verbose(int level);
  53
  54 /*
  55  * Original version of this function.
  56  * dm_errno is set to 0.
  57  *
  58  * Deprecated: Use the _with_errno_ versions above instead.
  59  */
  60 typedef void (*dm_log_fn) (int level, const char *file, int line,
  61                            const char *f, ...)
  62     __attribute__ ((format(printf, 4, 5)));
  63 void dm_log_init(dm_log_fn fn);
  64 /*
  65  * For backward-compatibility, indicate that dm_log_init() was used
  66  * to set a non-default value of dm_log().
  67  */
  68 int dm_log_is_non_default(void);
  69
  70 enum {
  71         DM_DEVICE_CREATE,
  72         DM_DEVICE_RELOAD,
  73         DM_DEVICE_REMOVE,
  74         DM_DEVICE_REMOVE_ALL,
  75
  76         DM_DEVICE_SUSPEND,
  77         DM_DEVICE_RESUME,
  78
  79         DM_DEVICE_INFO,
  80         DM_DEVICE_DEPS,
  81         DM_DEVICE_RENAME,
  82
  83         DM_DEVICE_VERSION,
  84
  85         DM_DEVICE_STATUS,
  86         DM_DEVICE_TABLE,
  87         DM_DEVICE_WAITEVENT,
  88
  89         DM_DEVICE_LIST,
  90
  91         DM_DEVICE_CLEAR,
  92
  93         DM_DEVICE_MKNODES,
  94
  95         DM_DEVICE_LIST_VERSIONS,
  96
  97         DM_DEVICE_TARGET_MSG,
  98
  99         DM_DEVICE_SET_GEOMETRY
 100 };
 101
 102 /*
 103  * You will need to build a struct dm_task for
 104  * each ioctl command you want to execute.
 105  */
 106
 107 struct dm_task;
 108
 109 struct dm_task *dm_task_create(int type);
 110 void dm_task_destroy(struct dm_task *dmt);
 111
 112 int dm_task_set_name(struct dm_task *dmt, const char *name);
 113 int dm_task_set_uuid(struct dm_task *dmt, const char *uuid);
 114
 115 /*
 116  * Retrieve attributes after an info.
 117  */
 118 struct dm_info {
 119         int exists;
 120         int suspended;
 121         int live_table;
 122         int inactive_table;
 123         int32_t open_count;
 124         uint32_t event_nr;
 125         uint32_t major;
 126         uint32_t minor;         /* minor device number */
 127         int read_only;          /* 0:read-write; 1:read-only */
 128
 129         int32_t target_count;
 130 };
 131
 132 struct dm_deps {
 133         uint32_t count;
 134         uint32_t filler;
 135         uint64_t device[0];
 136 };
 137
 138 struct dm_names {
 139         uint64_t dev;
 140         uint32_t next;          /* Offset to next struct from start of this struct */
 141         char name[0];
 142 };
 143
 144 struct dm_versions {
 145         uint32_t next;          /* Offset to next struct from start of this struct */
 146         uint32_t version[3];
 147
 148         char name[0];
 149 };
 150
 151 int dm_get_library_version(char *version, size_t size);
 152 int dm_task_get_driver_version(struct dm_task *dmt, char *version, size_t size);
 153 int dm_task_get_info(struct dm_task *dmt, struct dm_info *dmi);
 154 const char *dm_task_get_name(const struct dm_task *dmt);
 155 const char *dm_task_get_uuid(const struct dm_task *dmt);
 156
 157 struct dm_deps *dm_task_get_deps(struct dm_task *dmt);
 158 struct dm_names *dm_task_get_names(struct dm_task *dmt);
 159 struct dm_versions *dm_task_get_versions(struct dm_task *dmt);
 160
 161 int dm_task_set_ro(struct dm_task *dmt);
 162 int dm_task_set_newname(struct dm_task *dmt, const char *newname);
 163 int dm_task_set_minor(struct dm_task *dmt, int minor);
 164 int dm_task_set_major(struct dm_task *dmt, int major);
 165 int dm_task_set_major_minor(struct dm_task *dmt, int major, int minor, int allow_default_major_fallback);
 166 int dm_task_set_uid(struct dm_task *dmt, uid_t uid);
 167 int dm_task_set_gid(struct dm_task *dmt, gid_t gid);
 168 int dm_task_set_mode(struct dm_task *dmt, mode_t mode);
 169 int dm_task_set_cookie(struct dm_task *dmt, uint32_t *cookie, uint16_t flags);
 170 int dm_task_set_event_nr(struct dm_task *dmt, uint32_t event_nr);
 171 int dm_task_set_geometry(struct dm_task *dmt, const char *cylinders, const char *heads, const char *sectors, const char *start);
 172 int dm_task_set_message(struct dm_task *dmt, const char *message);
 173 int dm_task_set_sector(struct dm_task *dmt, uint64_t sector);
 174 int dm_task_no_flush(struct dm_task *dmt);
 175 int dm_task_no_open_count(struct dm_task *dmt);
 176 int dm_task_skip_lockfs(struct dm_task *dmt);
 177 int dm_task_query_inactive_table(struct dm_task *dmt);
 178 int dm_task_suppress_identical_reload(struct dm_task *dmt);
 179
 180 /*
 181  * Control read_ahead.
 182  */
 183 #define DM_READ_AHEAD_AUTO UINT32_MAX   /* Use kernel default readahead */
 184 #define DM_READ_AHEAD_NONE 0            /* Disable readahead */
 185
 186 #define DM_READ_AHEAD_MINIMUM_FLAG      0x1     /* Value supplied is minimum */
 187
 188 /*
 189  * Read ahead is set with DM_DEVICE_CREATE with a table or DM_DEVICE_RESUME.
 190  */
 191 int dm_task_set_read_ahead(struct dm_task *dmt, uint32_t read_ahead,
 192                            uint32_t read_ahead_flags);
 193 uint32_t dm_task_get_read_ahead(const struct dm_task *dmt,
 194                                 uint32_t *read_ahead);
 195
 196 /*
 197  * Use these to prepare for a create or reload.
 198  */
 199 int dm_task_add_target(struct dm_task *dmt,
 200                        uint64_t start,
 201                        uint64_t size, const char *ttype, const char *params);
 202
 203 /*
 204  * Format major/minor numbers correctly for input to driver.
 205  */
 206 #define DM_FORMAT_DEV_BUFSIZE   13      /* Minimum bufsize to handle worst case. */
 207 int dm_format_dev(char *buf, int bufsize, uint32_t dev_major, uint32_t dev_minor);
 208
 209 /* Use this to retrive target information returned from a STATUS call */
 210 void *dm_get_next_target(struct dm_task *dmt,
 211                          void *next, uint64_t *start, uint64_t *length,
 212                          char **target_type, char **params);
 213
 214 /*
 215  * Call this to actually run the ioctl.
 216  */
 217 int dm_task_run(struct dm_task *dmt);
 218
 219 /*
 220  * Call this to make or remove the device nodes associated with previously
 221  * issued commands.
 222  */
 223 void dm_task_update_nodes(void);
 224
 225 /*
 226  * Configure the device-mapper directory
 227  */
 228 int dm_set_dev_dir(const char *dir);
 229 const char *dm_dir(void);
 230
 231 /*
 232  * Determine whether a major number belongs to device-mapper or not.
 233  */
 234 int dm_is_dm_major(uint32_t major);
 235
 236 /*
 237  * Release library resources
 238  */
 239 void dm_lib_release(void);
 240 void dm_lib_exit(void) __attribute((destructor));
 241
 242 /*
 243  * Use NULL for all devices.
 244  */
 245 int dm_mknodes(const char *name);
 246 int dm_driver_version(char *version, size_t size);
 247
 248 /******************************************************
 249  * Functions to build and manipulate trees of devices *
 250  ******************************************************/
 251 struct dm_tree;
 252 struct dm_tree_node;
 253
 254 /*
 255  * Initialise an empty dependency tree.
 256  *
 257  * The tree consists of a root node together with one node for each mapped
 258  * device which has child nodes for each device referenced in its table.
 259  *
 260  * Every node in the tree has one or more children and one or more parents.
 261  *
 262  * The root node is the parent/child of every node that doesn't have other
 263  * parents/children.
 264  */
 265 struct dm_tree *dm_tree_create(void);
 266 void dm_tree_free(struct dm_tree *tree);
 267
 268 /*
 269  * Add nodes to the tree for a given device and all the devices it uses.
 270  */
 271 int dm_tree_add_dev(struct dm_tree *tree, uint32_t major, uint32_t minor);
 272
 273 /*
 274  * Add a new node to the tree if it doesn't already exist.
 275  */
 276 struct dm_tree_node *dm_tree_add_new_dev(struct dm_tree *tree,
 277                                          const char *name,
 278                                          const char *uuid,
 279                                          uint32_t major, uint32_t minor,
 280                                          int read_only,
 281                                          int clear_inactive,
 282                                          void *context);
 283 struct dm_tree_node *dm_tree_add_new_dev_with_udev_flags(struct dm_tree *tree,
 284                                                          const char *name,
 285                                                          const char *uuid,
 286                                                          uint32_t major,
 287                                                          uint32_t minor,
 288                                                          int read_only,
 289                                                          int clear_inactive,
 290                                                          void *context,
 291                                                          uint16_t udev_flags);
 292
 293 /*
 294  * Search for a node in the tree.
 295  * Set major and minor to 0 or uuid to NULL to get the root node.
 296  */
 297 struct dm_tree_node *dm_tree_find_node(struct dm_tree *tree,
 298                                           uint32_t major,
 299                                           uint32_t minor);
 300 struct dm_tree_node *dm_tree_find_node_by_uuid(struct dm_tree *tree,
 301                                                   const char *uuid);
 302
 303 /*
 304  * Use this to walk through all children of a given node.
 305  * Set handle to NULL in first call.
 306  * Returns NULL after the last child.
 307  * Set inverted to use inverted tree.
 308  */
 309 struct dm_tree_node *dm_tree_next_child(void **handle,
 310                                            struct dm_tree_node *parent,
 311                                            uint32_t inverted);
 312
 313 /*
 314  * Get properties of a node.
 315  */
 316 const char *dm_tree_node_get_name(struct dm_tree_node *node);
 317 const char *dm_tree_node_get_uuid(struct dm_tree_node *node);
 318 const struct dm_info *dm_tree_node_get_info(struct dm_tree_node *node);
 319 void *dm_tree_node_get_context(struct dm_tree_node *node);
 320 int dm_tree_node_size_changed(struct dm_tree_node *dnode);
 321
 322 /*
 323  * Returns the number of children of the given node (excluding the root node).
 324  * Set inverted for the number of parents.
 325  */
 326 int dm_tree_node_num_children(struct dm_tree_node *node, uint32_t inverted);
 327
 328 /*
 329  * Deactivate a device plus all dependencies.
 330  * Ignores devices that don't have a uuid starting with uuid_prefix.
 331  */
 332 int dm_tree_deactivate_children(struct dm_tree_node *dnode,
 333                                    const char *uuid_prefix,
 334                                    size_t uuid_prefix_len);
 335 /*
 336  * Preload/create a device plus all dependencies.
 337  * Ignores devices that don't have a uuid starting with uuid_prefix.
 338  */
 339 int dm_tree_preload_children(struct dm_tree_node *dnode,
 340                              const char *uuid_prefix,
 341                              size_t uuid_prefix_len);
 342
 343 /*
 344  * Resume a device plus all dependencies.
 345  * Ignores devices that don't have a uuid starting with uuid_prefix.
 346  */
 347 int dm_tree_activate_children(struct dm_tree_node *dnode,
 348                               const char *uuid_prefix,
 349                               size_t uuid_prefix_len);
 350
 351 /*
 352  * Suspend a device plus all dependencies.
 353  * Ignores devices that don't have a uuid starting with uuid_prefix.
 354  */
 355 int dm_tree_suspend_children(struct dm_tree_node *dnode,
 356                                    const char *uuid_prefix,
 357                                    size_t uuid_prefix_len);
 358
 359 /*
 360  * Skip the filesystem sync when suspending.
 361  * Does nothing with other functions.
 362  * Use this when no snapshots are involved.
 363  */
 364 void dm_tree_skip_lockfs(struct dm_tree_node *dnode);
 365
 366 /*
 367  * Set the 'noflush' flag when suspending devices.
 368  * If the kernel supports it, instead of erroring outstanding I/O that
 369  * cannot be completed, the I/O is queued and resubmitted when the
 370  * device is resumed.  This affects multipath devices when all paths
 371  * have failed and queue_if_no_path is set, and mirror devices when
 372  * block_on_error is set and the mirror log has failed.
 373  */
 374 void dm_tree_use_no_flush_suspend(struct dm_tree_node *dnode);
 375
 376 /*
 377  * Is the uuid prefix present in the tree?
 378  * Only returns 0 if every node was checked successfully.
 379  * Returns 1 if the tree walk has to be aborted.
 380  */
 381 int dm_tree_children_use_uuid(struct dm_tree_node *dnode,
 382                                  const char *uuid_prefix,
 383                                  size_t uuid_prefix_len);
 384
 385 /*
 386  * Construct tables for new nodes before activating them.
 387  */
 388 int dm_tree_node_add_snapshot_origin_target(struct dm_tree_node *dnode,
 389                                                uint64_t size,
 390                                                const char *origin_uuid);
 391 int dm_tree_node_add_snapshot_target(struct dm_tree_node *node,
 392                                         uint64_t size,
 393                                         const char *origin_uuid,
 394                                         const char *cow_uuid,
 395                                         int persistent,
 396                                         uint32_t chunk_size);
 397 int dm_tree_node_add_error_target(struct dm_tree_node *node,
 398                                      uint64_t size);
 399 int dm_tree_node_add_zero_target(struct dm_tree_node *node,
 400                                     uint64_t size);
 401 int dm_tree_node_add_linear_target(struct dm_tree_node *node,
 402                                       uint64_t size);
 403 int dm_tree_node_add_striped_target(struct dm_tree_node *node,
 404                                        uint64_t size,
 405                                        uint32_t stripe_size);
 406
 407 #define DM_CRYPT_IV_DEFAULT     UINT64_C(-1)    /* iv_offset == seg offset */
 408 /*
 409  * Function accepts one string in cipher specification
 410  * (chainmode and iv should be NULL because included in cipher string)
 411  *   or
 412  * separate arguments which will be joined to "cipher-chainmode-iv"
 413  */
 414 int dm_tree_node_add_crypt_target(struct dm_tree_node *node,
 415                                   uint64_t size,
 416                                   const char *cipher,
 417                                   const char *chainmode,
 418                                   const char *iv,
 419                                   uint64_t iv_offset,
 420                                   const char *key);
 421 int dm_tree_node_add_mirror_target(struct dm_tree_node *node,
 422                                       uint64_t size);
 423
 424 /* Mirror log flags */
 425 #define DM_NOSYNC               0x00000001      /* Known already in sync */
 426 #define DM_FORCESYNC            0x00000002      /* Force resync */
 427 #define DM_BLOCK_ON_ERROR       0x00000004      /* On error, suspend I/O */
 428 #define DM_CORELOG              0x00000008      /* In-memory log */
 429
 430 int dm_tree_node_add_mirror_target_log(struct dm_tree_node *node,
 431                                           uint32_t region_size,
 432                                           unsigned clustered,
 433                                           const char *log_uuid,
 434                                           unsigned area_count,
 435                                           uint32_t flags);
 436 int dm_tree_node_add_target_area(struct dm_tree_node *node,
 437                                     const char *dev_name,
 438                                     const char *dlid,
 439                                     uint64_t offset);
 440
 441 /*
 442  * Set readahead (in sectors) after loading the node.
 443  */
 444 void dm_tree_node_set_read_ahead(struct dm_tree_node *dnode,
 445                                  uint32_t read_ahead,
 446                                  uint32_t read_ahead_flags);
 447
 448 void dm_tree_set_cookie(struct dm_tree_node *node, uint32_t cookie);
 449 uint32_t dm_tree_get_cookie(struct dm_tree_node *node);
 450
 451 /*****************************************************************************
 452  * Library functions
 453  *****************************************************************************/
 454
 455 /*******************
 456  * Memory management
 457  *******************/
 458
 459 void *dm_malloc_aux(size_t s, const char *file, int line);
 460 void *dm_malloc_aux_debug(size_t s, const char *file, int line);
 461 char *dm_strdup_aux(const char *str, const char *file, int line);
 462 void dm_free_aux(void *p);
 463 void *dm_realloc_aux(void *p, unsigned int s, const char *file, int line);
 464 int dm_dump_memory_debug(void);
 465 void dm_bounds_check_debug(void);
 466
 467 #ifdef DEBUG_MEM
 468
 469 #  define dm_malloc(s) dm_malloc_aux_debug((s), __FILE__, __LINE__)
 470 #  define dm_strdup(s) dm_strdup_aux((s), __FILE__, __LINE__)
 471 #  define dm_free(p) dm_free_aux(p)
 472 #  define dm_realloc(p, s) dm_realloc_aux(p, s, __FILE__, __LINE__)
 473 #  define dm_dump_memory() dm_dump_memory_debug()
 474 #  define dm_bounds_check() dm_bounds_check_debug()
 475
 476 #else
 477
 478 #  define dm_malloc(s) dm_malloc_aux((s), __FILE__, __LINE__)
 479 #  define dm_strdup(s) strdup(s)
 480 #  define dm_free(p) free(p)
 481 #  define dm_realloc(p, s) realloc(p, s)
 482 #  define dm_dump_memory() {}
 483 #  define dm_bounds_check() {}
 484
 485 #endif
 486
 487
 488 /*
 489  * The pool allocator is useful when you are going to allocate
 490  * lots of memory, use the memory for a bit, and then free the
 491  * memory in one go.  A surprising amount of code has this usage
 492  * profile.
 493  *
 494  * You should think of the pool as an infinite, contiguous chunk
 495  * of memory.  The front of this chunk of memory contains
 496  * allocated objects, the second half is free.  dm_pool_alloc grabs
 497  * the next 'size' bytes from the free half, in effect moving it
 498  * into the allocated half.  This operation is very efficient.
 499  *
 500  * dm_pool_free frees the allocated object *and* all objects
 501  * allocated after it.  It is important to note this semantic
 502  * difference from malloc/free.  This is also extremely
 503  * efficient, since a single dm_pool_free can dispose of a large
 504  * complex object.
 505  *
 506  * dm_pool_destroy frees all allocated memory.
 507  *
 508  * eg, If you are building a binary tree in your program, and
 509  * know that you are only ever going to insert into your tree,
 510  * and not delete (eg, maintaining a symbol table for a
 511  * compiler).  You can create yourself a pool, allocate the nodes
 512  * from it, and when the tree becomes redundant call dm_pool_destroy
 513  * (no nasty iterating through the tree to free nodes).
 514  *
 515  * eg, On the other hand if you wanted to repeatedly insert and
 516  * remove objects into the tree, you would be better off
 517  * allocating the nodes from a free list; you cannot free a
 518  * single arbitrary node with pool.
 519  */
 520
 521 struct dm_pool;
 522
 523 /* constructor and destructor */
 524 struct dm_pool *dm_pool_create(const char *name, size_t chunk_hint);
 525 void dm_pool_destroy(struct dm_pool *p);
 526
 527 /* simple allocation/free routines */
 528 void *dm_pool_alloc(struct dm_pool *p, size_t s);
 529 void *dm_pool_alloc_aligned(struct dm_pool *p, size_t s, unsigned alignment);
 530 void dm_pool_empty(struct dm_pool *p);
 531 void dm_pool_free(struct dm_pool *p, void *ptr);
 532
 533 /*
 534  * Object building routines:
 535  *
 536  * These allow you to 'grow' an object, useful for
 537  * building strings, or filling in dynamic
 538  * arrays.
 539  *
 540  * It's probably best explained with an example:
 541  *
 542  * char *build_string(struct dm_pool *mem)
 543  * {
 544  *      int i;
 545  *      char buffer[16];
 546  *
 547  *      if (!dm_pool_begin_object(mem, 128))
 548  *              return NULL;
 549  *
 550  *      for (i = 0; i < 50; i++) {
 551  *              snprintf(buffer, sizeof(buffer), "%d, ", i);
 552  *              if (!dm_pool_grow_object(mem, buffer, 0))
 553  *                      goto bad;
 554  *      }
 555  *
 556  *      // add null
 557  *      if (!dm_pool_grow_object(mem, "\0", 1))
 558  *              goto bad;
 559  *
 560  *      return dm_pool_end_object(mem);
 561  *
 562  * bad:
 563  *
 564  *      dm_pool_abandon_object(mem);
 565  *      return NULL;
 566  *}
 567  *
 568  * So start an object by calling dm_pool_begin_object
 569  * with a guess at the final object size - if in
 570  * doubt make the guess too small.
 571  *
 572  * Then append chunks of data to your object with
 573  * dm_pool_grow_object.  Finally get your object with
 574  * a call to dm_pool_end_object.
 575  *
 576  * Setting delta to 0 means it will use strlen(extra).
 577  */
 578 int dm_pool_begin_object(struct dm_pool *p, size_t hint);
 579 int dm_pool_grow_object(struct dm_pool *p, const void *extra, size_t delta);
 580 void *dm_pool_end_object(struct dm_pool *p);
 581 void dm_pool_abandon_object(struct dm_pool *p);
 582
 583 /* utilities */
 584 char *dm_pool_strdup(struct dm_pool *p, const char *str);
 585 char *dm_pool_strndup(struct dm_pool *p, const char *str, size_t n);
 586 void *dm_pool_zalloc(struct dm_pool *p, size_t s);
 587
 588 /******************
 589  * bitset functions
 590  ******************/
 591
 592 typedef uint32_t *dm_bitset_t;
 593
 594 dm_bitset_t dm_bitset_create(struct dm_pool *mem, unsigned num_bits);
 595 void dm_bitset_destroy(dm_bitset_t bs);
 596
 597 void dm_bit_union(dm_bitset_t out, dm_bitset_t in1, dm_bitset_t in2);
 598 int dm_bit_get_first(dm_bitset_t bs);
 599 int dm_bit_get_next(dm_bitset_t bs, int last_bit);
 600
 601 #define DM_BITS_PER_INT (sizeof(int) * CHAR_BIT)
 602
 603 #define dm_bit(bs, i) \
 604    (bs[(i / DM_BITS_PER_INT) + 1] & (0x1 << (i & (DM_BITS_PER_INT - 1))))
 605
 606 #define dm_bit_set(bs, i) \
 607    (bs[(i / DM_BITS_PER_INT) + 1] |= (0x1 << (i & (DM_BITS_PER_INT - 1))))
 608
 609 #define dm_bit_clear(bs, i) \
 610    (bs[(i / DM_BITS_PER_INT) + 1] &= ~(0x1 << (i & (DM_BITS_PER_INT - 1))))
 611
 612 #define dm_bit_set_all(bs) \
 613    memset(bs + 1, -1, ((*bs / DM_BITS_PER_INT) + 1) * sizeof(int))
 614
 615 #define dm_bit_clear_all(bs) \
 616    memset(bs + 1, 0, ((*bs / DM_BITS_PER_INT) + 1) * sizeof(int))
 617
 618 #define dm_bit_copy(bs1, bs2) \
 619    memcpy(bs1 + 1, bs2 + 1, ((*bs1 / DM_BITS_PER_INT) + 1) * sizeof(int))
 620
 621 /* Returns number of set bits */
 622 static inline unsigned hweight32(uint32_t i)
 623 {
 624         unsigned r = (i & 0x55555555) + ((i >> 1) & 0x55555555);
 625
 626         r =    (r & 0x33333333) + ((r >>  2) & 0x33333333);
 627         r =    (r & 0x0F0F0F0F) + ((r >>  4) & 0x0F0F0F0F);
 628         r =    (r & 0x00FF00FF) + ((r >>  8) & 0x00FF00FF);
 629         return (r & 0x0000FFFF) + ((r >> 16) & 0x0000FFFF);
 630 }
 631
 632 /****************
 633  * hash functions
 634  ****************/
 635
 636 struct dm_hash_table;
 637 struct dm_hash_node;
 638
 639 typedef void (*dm_hash_iterate_fn) (void *data);
 640
 641 struct dm_hash_table *dm_hash_create(unsigned size_hint);
 642 void dm_hash_destroy(struct dm_hash_table *t);
 643 void dm_hash_wipe(struct dm_hash_table *t);
 644
 645 void *dm_hash_lookup(struct dm_hash_table *t, const char *key);
 646 int dm_hash_insert(struct dm_hash_table *t, const char *key, void *data);
 647 void dm_hash_remove(struct dm_hash_table *t, const char *key);
 648
 649 void *dm_hash_lookup_binary(struct dm_hash_table *t, const char *key, uint32_t len);
 650 int dm_hash_insert_binary(struct dm_hash_table *t, const char *key, uint32_t len,
 651                        void *data);
 652 void dm_hash_remove_binary(struct dm_hash_table *t, const char *key, uint32_t len);
 653
 654 unsigned dm_hash_get_num_entries(struct dm_hash_table *t);
 655 void dm_hash_iter(struct dm_hash_table *t, dm_hash_iterate_fn f);
 656
 657 char *dm_hash_get_key(struct dm_hash_table *t, struct dm_hash_node *n);
 658 void *dm_hash_get_data(struct dm_hash_table *t, struct dm_hash_node *n);
 659 struct dm_hash_node *dm_hash_get_first(struct dm_hash_table *t);
 660 struct dm_hash_node *dm_hash_get_next(struct dm_hash_table *t, struct dm_hash_node *n);
 661
 662 #define dm_hash_iterate(v, h) \
 663         for (v = dm_hash_get_first(h); v; \
 664              v = dm_hash_get_next(h, v))
 665
 666 /****************
 667  * list functions
 668  ****************/
 669
 670 /*
 671  * A list consists of a list head plus elements.
 672  * Each element has 'next' and 'previous' pointers.
 673  * The list head's pointers point to the first and the last element.
 674  */
 675
 676 struct dm_list {
 677         struct dm_list *n, *p;
 678 };
 679
 680 /*
 681  * Initialise a list before use.
 682  * The list head's next and previous pointers point back to itself.
 683  */
 684 #define DM_LIST_INIT(name)      struct dm_list name = { &(name), &(name) }
 685 void dm_list_init(struct dm_list *head);
 686
 687 /*
 688  * Insert an element before 'head'.
 689  * If 'head' is the list head, this adds an element to the end of the list.
 690  */
 691 void dm_list_add(struct dm_list *head, struct dm_list *elem);
 692
 693 /*
 694  * Insert an element after 'head'.
 695  * If 'head' is the list head, this adds an element to the front of the list.
 696  */
 697 void dm_list_add_h(struct dm_list *head, struct dm_list *elem);
 698
 699 /*
 700  * Delete an element from its list.
 701  * Note that this doesn't change the element itself - it may still be safe
 702  * to follow its pointers.
 703  */
 704 void dm_list_del(struct dm_list *elem);
 705
 706 /*
 707  * Remove an element from existing list and insert before 'head'.
 708  */
 709 void dm_list_move(struct dm_list *head, struct dm_list *elem);
 710
 711 /*
 712  * Is the list empty?
 713  */
 714 int dm_list_empty(const struct dm_list *head);
 715
 716 /*
 717  * Is this the first element of the list?
 718  */
 719 int dm_list_start(const struct dm_list *head, const struct dm_list *elem);
 720
 721 /*
 722  * Is this the last element of the list?
 723  */
 724 int dm_list_end(const struct dm_list *head, const struct dm_list *elem);
 725
 726 /*
 727  * Return first element of the list or NULL if empty
 728  */
 729 struct dm_list *dm_list_first(const struct dm_list *head);
 730
 731 /*
 732  * Return last element of the list or NULL if empty
 733  */
 734 struct dm_list *dm_list_last(const struct dm_list *head);
 735
 736 /*
 737  * Return the previous element of the list, or NULL if we've reached the start.
 738  */
 739 struct dm_list *dm_list_prev(const struct dm_list *head, const struct dm_list *elem);
 740
 741 /*
 742  * Return the next element of the list, or NULL if we've reached the end.
 743  */
 744 struct dm_list *dm_list_next(const struct dm_list *head, const struct dm_list *elem);
 745
 746 /*
 747  * Given the address v of an instance of 'struct dm_list' called 'head'
 748  * contained in a structure of type t, return the containing structure.
 749  */
 750 #define dm_list_struct_base(v, t, head) \
 751     ((t *)((uintptr_t)(v) - (uintptr_t)&((t *) 0)->head))
 752
 753 /*
 754  * Given the address v of an instance of 'struct dm_list list' contained in
 755  * a structure of type t, return the containing structure.
 756  */
 757 #define dm_list_item(v, t) dm_list_struct_base((v), t, list)
 758
 759 /*
 760  * Given the address v of one known element e in a known structure of type t,
 761  * return another element f.
 762  */
 763 #define dm_struct_field(v, t, e, f) \
 764     (((t *)((uintptr_t)(v) - (uintptr_t)&((t *) 0)->e))->f)
 765
 766 /*
 767  * Given the address v of a known element e in a known structure of type t,
 768  * return the list head 'list'
 769  */
 770 #define dm_list_head(v, t, e) dm_struct_field(v, t, e, list)
 771
 772 /*
 773  * Set v to each element of a list in turn.
 774  */
 775 #define dm_list_iterate(v, head) \
 776         for (v = (head)->n; v != head; v = v->n)
 777
 778 /*
 779  * Set v to each element in a list in turn, starting from the element
 780  * in front of 'start'.
 781  * You can use this to 'unwind' a list_iterate and back out actions on
 782  * already-processed elements.
 783  * If 'start' is 'head' it walks the list backwards.
 784  */
 785 #define dm_list_uniterate(v, head, start) \
 786         for (v = (start)->p; v != head; v = v->p)
 787
 788 /*
 789  * A safe way to walk a list and delete and free some elements along
 790  * the way.
 791  * t must be defined as a temporary variable of the same type as v.
 792  */
 793 #define dm_list_iterate_safe(v, t, head) \
 794         for (v = (head)->n, t = v->n; v != head; v = t, t = v->n)
 795
 796 /*
 797  * Walk a list, setting 'v' in turn to the containing structure of each item.
 798  * The containing structure should be the same type as 'v'.
 799  * The 'struct dm_list' variable within the containing structure is 'field'.
 800  */
 801 #define dm_list_iterate_items_gen(v, head, field) \
 802         for (v = dm_list_struct_base((head)->n, typeof(*v), field); \
 803              &v->field != (head); \
 804              v = dm_list_struct_base(v->field.n, typeof(*v), field))
 805
 806 /*
 807  * Walk a list, setting 'v' in turn to the containing structure of each item.
 808  * The containing structure should be the same type as 'v'.
 809  * The list should be 'struct dm_list list' within the containing structure.
 810  */
 811 #define dm_list_iterate_items(v, head) dm_list_iterate_items_gen(v, (head), list)
 812
 813 /*
 814  * Walk a list, setting 'v' in turn to the containing structure of each item.
 815  * The containing structure should be the same type as 'v'.
 816  * The 'struct dm_list' variable within the containing structure is 'field'.
 817  * t must be defined as a temporary variable of the same type as v.
 818  */
 819 #define dm_list_iterate_items_gen_safe(v, t, head, field) \
 820         for (v = dm_list_struct_base((head)->n, typeof(*v), field), \
 821              t = dm_list_struct_base(v->field.n, typeof(*v), field); \
 822              &v->field != (head); \
 823              v = t, t = dm_list_struct_base(v->field.n, typeof(*v), field))
 824 /*
 825  * Walk a list, setting 'v' in turn to the containing structure of each item.
 826  * The containing structure should be the same type as 'v'.
 827  * The list should be 'struct dm_list list' within the containing structure.
 828  * t must be defined as a temporary variable of the same type as v.
 829  */
 830 #define dm_list_iterate_items_safe(v, t, head) \
 831         dm_list_iterate_items_gen_safe(v, t, (head), list)
 832
 833 /*
 834  * Walk a list backwards, setting 'v' in turn to the containing structure
 835  * of each item.
 836  * The containing structure should be the same type as 'v'.
 837  * The 'struct dm_list' variable within the containing structure is 'field'.
 838  */
 839 #define dm_list_iterate_back_items_gen(v, head, field) \
 840         for (v = dm_list_struct_base((head)->p, typeof(*v), field); \
 841              &v->field != (head); \
 842              v = dm_list_struct_base(v->field.p, typeof(*v), field))
 843
 844 /*
 845  * Walk a list backwards, setting 'v' in turn to the containing structure
 846  * of each item.
 847  * The containing structure should be the same type as 'v'.
 848  * The list should be 'struct dm_list list' within the containing structure.
 849  */
 850 #define dm_list_iterate_back_items(v, head) dm_list_iterate_back_items_gen(v, (head), list)
 851
 852 /*
 853  * Return the number of elements in a list by walking it.
 854  */
 855 unsigned int dm_list_size(const struct dm_list *head);
 856
 857 /*********
 858  * selinux
 859  *********/
 860 int dm_set_selinux_context(const char *path, mode_t mode);
 861
 862 /*********************
 863  * string manipulation
 864  *********************/
 865
 866 /*
 867  * Break up the name of a mapped device into its constituent
 868  * Volume Group, Logical Volume and Layer (if present).
 869  * If mem is supplied, the result is allocated from the mempool.
 870  * Otherwise the strings are changed in situ.
 871  */
 872 int dm_split_lvm_name(struct dm_pool *mem, const char *dmname,
 873                       char **vgname, char **lvname, char **layer);
 874
 875 /*
 876  * Destructively split buffer into NULL-separated words in argv.
 877  * Returns number of words.
 878  */
 879 int dm_split_words(char *buffer, unsigned max,
 880                    unsigned ignore_comments, /* Not implemented */
 881                    char **argv);
 882
 883 /*
 884  * Returns -1 if buffer too small
 885  */
 886 int dm_snprintf(char *buf, size_t bufsize, const char *format, ...);
 887
 888 /*
 889  * Returns pointer to the last component of the path.
 890  */
 891 char *dm_basename(const char *path);
 892
 893 /**************************
 894  * file/stream manipulation
 895  **************************/
 896
 897 /*
 898  * Create a directory (with parent directories if necessary).
 899  * Returns 1 on success, 0 on failure.
 900  */
 901 int dm_create_dir(const char *dir);
 902
 903 /*
 904  * Close a stream, with nicer error checking than fclose's.
 905  * Derived from gnulib's close-stream.c.
 906  *
 907  * Close "stream".  Return 0 if successful, and EOF (setting errno)
 908  * otherwise.  Upon failure, set errno to 0 if the error number
 909  * cannot be determined.  Useful mainly for writable streams.
 910  */
 911 int dm_fclose(FILE *stream);
 912
 913 /*
 914  * Returns size of a buffer which is allocated with dm_malloc.
 915  * Pointer to the buffer is stored in *buf.
 916  * Returns -1 on failure leaving buf undefined.
 917  */
 918 int dm_asprintf(char **buf, const char *format, ...);
 919
 920 /*********************
 921  * regular expressions
 922  *********************/
 923 struct dm_regex;
 924
 925 /*
 926  * Initialise an array of num patterns for matching.
 927  * Uses memory from mem.
 928  */
 929 struct dm_regex *dm_regex_create(struct dm_pool *mem, const char **patterns,
 930                                  unsigned num_patterns);
 931
 932 /*
 933  * Match string s against the patterns.
 934  * Returns the index of the highest pattern in the array that matches,
 935  * or -1 if none match.
 936  */
 937 int dm_regex_match(struct dm_regex *regex, const char *s);
 938
 939 /*********************
 940  * reporting functions
 941  *********************/
 942
 943 struct dm_report_object_type {
 944         uint32_t id;                    /* Powers of 2 */
 945         const char *desc;
 946         const char *prefix;             /* field id string prefix (optional) */
 947         void *(*data_fn)(void *object); /* callback from report_object() */
 948 };
 949
 950 struct dm_report_field;
 951
 952 /*
 953  * dm_report_field_type flags
 954  */
 955 #define DM_REPORT_FIELD_MASK            0x000000FF
 956 #define DM_REPORT_FIELD_ALIGN_MASK      0x0000000F
 957 #define DM_REPORT_FIELD_ALIGN_LEFT      0x00000001
 958 #define DM_REPORT_FIELD_ALIGN_RIGHT     0x00000002
 959 #define DM_REPORT_FIELD_TYPE_MASK       0x000000F0
 960 #define DM_REPORT_FIELD_TYPE_STRING     0x00000010
 961 #define DM_REPORT_FIELD_TYPE_NUMBER     0x00000020
 962
 963 struct dm_report;
 964 struct dm_report_field_type {
 965         uint32_t type;          /* object type id */
 966         uint32_t flags;         /* DM_REPORT_FIELD_* */
 967         uint32_t offset;        /* byte offset in the object */
 968         int32_t width;          /* default width */
 969         const char id[32];      /* string used to specify the field */
 970         const char heading[32]; /* string printed in header */
 971         int (*report_fn)(struct dm_report *rh, struct dm_pool *mem,
 972                          struct dm_report_field *field, const void *data,
 973                          void *private);
 974         const char *desc;       /* description of the field */
 975 };
 976
 977 /*
 978  * dm_report_init output_flags
 979  */
 980 #define DM_REPORT_OUTPUT_MASK                   0x000000FF
 981 #define DM_REPORT_OUTPUT_ALIGNED                0x00000001
 982 #define DM_REPORT_OUTPUT_BUFFERED               0x00000002
 983 #define DM_REPORT_OUTPUT_HEADINGS               0x00000004
 984 #define DM_REPORT_OUTPUT_FIELD_NAME_PREFIX      0x00000008
 985 #define DM_REPORT_OUTPUT_FIELD_UNQUOTED         0x00000010
 986 #define DM_REPORT_OUTPUT_COLUMNS_AS_ROWS        0x00000020
 987
 988 struct dm_report *dm_report_init(uint32_t *report_types,
 989                                  const struct dm_report_object_type *types,
 990                                  const struct dm_report_field_type *fields,
 991                                  const char *output_fields,
 992                                  const char *output_separator,
 993                                  uint32_t output_flags,
 994                                  const char *sort_keys,
 995                                  void *private);
 996 int dm_report_object(struct dm_report *rh, void *object);
 997 int dm_report_output(struct dm_report *rh);
 998 void dm_report_free(struct dm_report *rh);
 999
1000 /*
1001  * Prefix added to each field name with DM_REPORT_OUTPUT_FIELD_NAME_PREFIX
1002  */
1003 int dm_report_set_output_field_name_prefix(struct dm_report *rh,
1004                                            const char *report_prefix);
1005
1006 /*
1007  * Report functions are provided for simple data types.
1008  * They take care of allocating copies of the data.
1009  */
1010 int dm_report_field_string(struct dm_report *rh, struct dm_report_field *field,
1011                            const char **data);
1012 int dm_report_field_int32(struct dm_report *rh, struct dm_report_field *field,
1013                           const int32_t *data);
1014 int dm_report_field_uint32(struct dm_report *rh, struct dm_report_field *field,
1015                            const uint32_t *data);
1016 int dm_report_field_int(struct dm_report *rh, struct dm_report_field *field,
1017                         const int *data);
1018 int dm_report_field_uint64(struct dm_report *rh, struct dm_report_field *field,
1019                            const uint64_t *data);
1020
1021 /*
1022  * For custom fields, allocate the data in 'mem' and use
1023  * dm_report_field_set_value().
1024  * 'sortvalue' may be NULL if it matches 'value'
1025  */
1026 void dm_report_field_set_value(struct dm_report_field *field, const void *value,
1027                                const void *sortvalue);
1028
1029 /* Cookie prefixes.
1030  * The cookie value consists of a prefix (16 bits) and a base (16 bits).
1031  * We can use the prefix to store the flags. These flags are sent to
1032  * kernel within given dm task. When returned back to userspace in
1033  * DM_COOKIE udev environment variable, we can control several aspects
1034  * of udev rules we use by decoding the cookie prefix. When doing the
1035  * notification, we replace the cookie prefix with DM_COOKIE_MAGIC,
1036  * so we notify the right semaphore.
1037  * It is still possible to use cookies for passing the flags to udev
1038  * rules even when udev_sync is disabled. The base part of the cookie
1039  * will be zero (there's no notification semaphore) and prefix will be
1040  * set then. However, having udev_sync enabled is highly recommended.
1041  */
1042 #define DM_COOKIE_MAGIC 0x0D4D
1043 #define DM_UDEV_FLAGS_MASK 0xFFFF0000
1044 #define DM_UDEV_FLAGS_SHIFT 16
1045
1046 /*
1047  * DM_UDEV_DISABLE_DM_RULES_FLAG is set in case we need to disable
1048  * basic device-mapper udev rules that create symlinks in /dev/<DM_DIR>
1049  * directory. However, we can't reliably prevent creating default
1050  * nodes by udev (commonly /dev/dm-X, where X is a number).
1051  */
1052 #define DM_UDEV_DISABLE_DM_RULES_FLAG 0x0001
1053 /*
1054  * DM_UDEV_DISABLE_SUBSYTEM_RULES_FLAG is set in case we need to disable
1055  * subsystem udev rules, but still we need the general DM udev rules to
1056  * be applied (to create the nodes and symlinks under /dev and /dev/disk).
1057  */
1058 #define DM_UDEV_DISABLE_SUBSYSTEM_RULES_FLAG 0x0002
1059 /*
1060  * DM_UDEV_DISABLE_DISK_RULES_FLAG is set in case we need to disable
1061  * general DM rules that set symlinks in /dev/disk directory.
1062  */
1063 #define DM_UDEV_DISABLE_DISK_RULES_FLAG 0x0004
1064 /*
1065  * DM_UDEV_DISABLE_OTHER_RULES_FLAG is set in case we need to disable
1066  * all the other rules that are not general device-mapper nor subsystem
1067  * related (the rules belong to other software or packages). All foreign
1068  * rules should check this flag directly and they should ignore further
1069  * rule processing for such event.
1070  */
1071 #define DM_UDEV_DISABLE_OTHER_RULES_FLAG 0x0008
1072 /*
1073  * DM_UDEV_LOW_PRIORITY_FLAG is set in case we need to instruct the
1074  * udev rules to give low priority to the device that is currently
1075  * processed. For example, this provides a way to select which symlinks
1076  * could be overwritten by high priority ones if their names are equal.
1077  * Common situation is a name based on FS UUID while using origin and
1078  * snapshot devices.
1079  */
1080 #define DM_UDEV_LOW_PRIORITY_FLAG 0x0010
1081
1082 int dm_cookie_supported(void);
1083
1084 /*
1085  * Udev synchronisation functions.
1086  */
1087 void dm_udev_set_sync_support(int sync_with_udev);
1088 int dm_udev_get_sync_support(void);
1089 int dm_udev_complete(uint32_t cookie);
1090 int dm_udev_wait(uint32_t cookie);
1091
1092 #define DM_DEV_DIR_UMASK 0022
1093
1094 #endif                          /* LIB_DEVICE_MAPPER_H */