be.h revision 357667 
1/*-
2 * SPDX-License-Identifier: BSD-2-Clause-FreeBSD
3 *
4 * Copyright (c) 2017 Kyle J. Kneitinger <kyle@kneit.in>
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
8 * are met:
9 * 1. Redistributions of source code must retain the above copyright
10 *    notice, this list of conditions and the following disclaimer.
11 * 2. Redistributions in binary form must reproduce the above copyright
12 *    notice, this list of conditions and the following disclaimer in the
13 *    documentation and/or other materials provided with the distribution.
14 *
15 * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
16 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
19 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25 * SUCH DAMAGE.
26 *
27 * $FreeBSD: stable/11/lib/libbe/be.h 357667 2020-02-07 21:57:27Z kevans $
28 */
29
30#ifndef _LIBBE_H
31#define _LIBBE_H
32
33#include <libnvpair.h>
34#include <stdbool.h>
35
36#define BE_MAXPATHLEN    512
37
38typedef struct libbe_handle libbe_handle_t;
39
40typedef enum be_error {
41	BE_ERR_SUCCESS = 0,     /* No error */
42	BE_ERR_INVALIDNAME,     /* invalid boot env name */
43	BE_ERR_EXISTS,          /* boot env name already taken */
44	BE_ERR_NOENT,           /* boot env doesn't exist */
45	BE_ERR_PERMS,           /* insufficient permissions */
46	BE_ERR_DESTROYACT,      /* cannot destroy active boot env */
47	BE_ERR_DESTROYMNT,      /* destroying a mounted be requires force */
48	BE_ERR_BADPATH,		/* path not suitable for operation */
49	BE_ERR_PATHBUSY,	/* requested path is busy */
50	BE_ERR_PATHLEN,         /* provided name exceeds maximum length limit */
51	BE_ERR_BADMOUNT,        /* mountpoint is not '/' */
52	BE_ERR_NOORIGIN,        /* could not open snapshot's origin */
53	BE_ERR_MOUNTED,         /* boot environment is already mounted */
54	BE_ERR_NOMOUNT,         /* boot environment is not mounted */
55	BE_ERR_ZFSOPEN,         /* calling zfs_open() failed */
56	BE_ERR_ZFSCLONE,        /* error when calling zfs_clone to create be */
57	BE_ERR_IO,		/* error when doing some I/O operation */
58	BE_ERR_NOPOOL,		/* operation not supported on this pool */
59	BE_ERR_NOMEM,		/* insufficient memory */
60	BE_ERR_UNKNOWN,         /* unknown error */
61	BE_ERR_INVORIGIN,       /* invalid origin */
62	BE_ERR_HASCLONES,	/* snapshot has clones */
63} be_error_t;
64
65
66/* Library handling functions: be.c */
67libbe_handle_t *libbe_init(const char *root);
68void libbe_close(libbe_handle_t *);
69
70/* Bootenv information functions: be_info.c */
71const char *be_active_name(libbe_handle_t *);
72const char *be_active_path(libbe_handle_t *);
73const char *be_nextboot_name(libbe_handle_t *);
74const char *be_nextboot_path(libbe_handle_t *);
75const char *be_root_path(libbe_handle_t *);
76
77int be_get_bootenv_props(libbe_handle_t *, nvlist_t *);
78int be_get_dataset_props(libbe_handle_t *, const char *, nvlist_t *);
79int be_get_dataset_snapshots(libbe_handle_t *, const char *, nvlist_t *);
80int be_prop_list_alloc(nvlist_t **be_list);
81void be_prop_list_free(nvlist_t *be_list);
82
83int be_activate(libbe_handle_t *, const char *, bool);
84
85bool be_is_auto_snapshot_name(libbe_handle_t *, const char *);
86
87/* Bootenv creation functions */
88int be_create(libbe_handle_t *, const char *);
89int be_create_depth(libbe_handle_t *, const char *, const char *, int);
90int be_create_from_existing(libbe_handle_t *, const char *, const char *);
91int be_create_from_existing_snap(libbe_handle_t *, const char *, const char *);
92int be_snapshot(libbe_handle_t *, const char *, const char *, bool, char *);
93
94/* Bootenv manipulation functions */
95int be_rename(libbe_handle_t *, const char *, const char *);
96
97/* Bootenv removal functions */
98
99typedef enum {
100	BE_DESTROY_FORCE	= 1 << 0,
101	BE_DESTROY_ORIGIN	= 1 << 1,
102	BE_DESTROY_AUTOORIGIN	= 1 << 2,
103} be_destroy_opt_t;
104
105int be_destroy(libbe_handle_t *, const char *, int);
106
107/* Bootenv mounting functions: be_access.c */
108
109typedef enum {
110	BE_MNT_FORCE		= 1 << 0,
111	BE_MNT_DEEP		= 1 << 1,
112} be_mount_opt_t;
113
114int be_mount(libbe_handle_t *, char *, char *, int, char *);
115int be_unmount(libbe_handle_t *, char *, int);
116int be_mounted_at(libbe_handle_t *, const char *path, nvlist_t *);
117
118/* Error related functions: be_error.c */
119int libbe_errno(libbe_handle_t *);
120const char *libbe_error_description(libbe_handle_t *);
121void libbe_print_on_error(libbe_handle_t *, bool);
122
123/* Utility Functions */
124int be_root_concat(libbe_handle_t *, const char *, char *);
125int be_validate_name(libbe_handle_t * __unused, const char *);
126int be_validate_snap(libbe_handle_t *, const char *);
127int be_exists(libbe_handle_t *, char *);
128
129int be_export(libbe_handle_t *, const char *, int fd);
130int be_import(libbe_handle_t *, const char *, int fd);
131
132#if SOON
133int be_add_child(libbe_handle_t *, const char *, bool);
134#endif
135void be_nicenum(uint64_t num, char *buf, size_t buflen);
136
137#endif  /* _LIBBE_H */
138