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