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 */ 1095