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 */
hweight32(uint32_t i)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