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