| libbe.3 (11f2a1235087e1534e4dff7509a2d7b127a716f0) | libbe.3 (84e6121955e9b8fbf28e74f4905ca2772b886769) |
|---|---|
| 1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD 3.\" 4.\" Copyright (c) 2017 Kyle Kneitinger 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 --- 11 unchanged lines hidden (view full) --- 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.\" | 1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD 3.\" 4.\" Copyright (c) 2017 Kyle Kneitinger 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 --- 11 unchanged lines hidden (view full) --- 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.\" This manual page is based on the mp(3X) manual page from Sun Release 29.\" 4.1, dated 7 September 1989. It's an old, crufty, and relatively ugly 30.\" manual page, but it does document what appears to be the "traditional" 31.\" libmp interface. 32.\" | |
| 33.\" $FreeBSD$ 34.\" 35.Dd August 10, 2018 36.Dt LIBBE 3 37.Os 38.Sh NAME 39.Nm libbe | 28.\" $FreeBSD$ 29.\" 30.Dd August 10, 2018 31.Dt LIBBE 3 32.Os 33.Sh NAME 34.Nm libbe |
| 40.Nd library for creating, destroying and modifying ZFS boot environments. | 35.Nd library for creating, destroying and modifying ZFS boot environments 36.Sh LIBRARY 37.Lb be |
| 41.Sh SYNOPSIS 42.In be.h 43.Pp | 38.Sh SYNOPSIS 39.In be.h 40.Pp |
| 44Function prototypes are given in the main body of the text. | 41Function prototypes are given in the 42.Sx FUNCTION OVERVIEW 43section. |
| 45.Pp 46Applications using this interface must be linked with 47.Fl l Ns Ar be 48.Sh DESCRIPTION | 44.Pp 45Applications using this interface must be linked with 46.Fl l Ns Ar be 47.Sh DESCRIPTION |
| 49.Pp | |
| 50.Nm 51interfaces with libzfs to provide a set of functions for various operations 52regarding ZFS boot environments including "deep" boot environments in which 53a boot environments has child datasets. 54.Pp 55A context structure is passed to each function, allowing for a small amount 56of state to be retained, such as errors from previous operations. 57.\" TODO: describe break on err functionality | 48.Nm 49interfaces with libzfs to provide a set of functions for various operations 50regarding ZFS boot environments including "deep" boot environments in which 51a boot environments has child datasets. 52.Pp 53A context structure is passed to each function, allowing for a small amount 54of state to be retained, such as errors from previous operations. 55.\" TODO: describe break on err functionality |
| 58.Pp | 56.Sh FUNCTION OVERVIEW |
| 59.Ft "libbe_handle_t *" Ns | 57.Ft "libbe_handle_t *" Ns |
| 60.Fn libbe_init "void" ; | 58.Fn libbe_init void ; |
| 61.Pp 62.Ft void 63.Fn libbe_close "libbe_handle_t *" ; 64.Pp | 59.Pp 60.Ft void 61.Fn libbe_close "libbe_handle_t *" ; 62.Pp |
| 65.Ft "const char *" Ns | 63.Ft const char * Ns |
| 66.Fn be_active_name "libbe_handle_t *" ; 67.Pp | 64.Fn be_active_name "libbe_handle_t *" ; 65.Pp |
| 68.Ft "const char *" Ns | 66.Ft const char * Ns |
| 69.Fn be_active_path "libbe_handle_t *" ; 70.Pp | 67.Fn be_active_path "libbe_handle_t *" ; 68.Pp |
| 71.Ft "const char *" Ns | 69.Ft const char * Ns 70.Fn be_nextboot_name "libbe_handle_t *" ; 71.Pp 72.Ft const char * Ns 73.Fn be_nextboot_path "libbe_handle_t *" ; 74.Pp 75.Ft const char * Ns |
| 72.Fn be_root_path "libbe_handle_t *" ; 73.Pp | 76.Fn be_root_path "libbe_handle_t *" ; 77.Pp |
| 74.Ft "nvlist_t *" Ns 75.Fn libbe_handle_t "libbe_handle_t " ; | 78.Ft int 79.Fn be_create "libbe_handle_t *" "const char *" ; |
| 76.Pp 77.Ft int | 80.Pp 81.Ft int |
| 78.Fn be_create "libbe_handle_t *, const char *" ; | 82.Fn be_create_from_existing "libbe_handle_t *" "const char *" "const char *" ; |
| 79.Pp 80.Ft int | 83.Pp 84.Ft int |
| 81.Fn be_create_from_existing "libbe_handle_t *, const char *, const char *" ; | 85.Fn be_create_from_existing_snap "libbe_handle_t *" "const char *" "const char *" ; |
| 82.Pp 83.Ft int | 86.Pp 87.Ft int |
| 84.Fn be_rename "libbe_handle_t *, const char *, const char *" ; | 88.Fn be_rename "libbe_handle_t *" "const char *" "const char *" ; |
| 85.Pp | 89.Pp |
| 90.Ft int 91.Fn be_activate "libbe_handle_t *" "const char *" "bool" ; |
|
| 86.\" TODO: Write up of destroy options 87.\" typedef enum { 88.\" BE_DESTROY_FORCE = 1 << 0, 89.\" } be_destroy_opt_t; 90.Ft int | 92.\" TODO: Write up of destroy options 93.\" typedef enum { 94.\" BE_DESTROY_FORCE = 1 << 0, 95.\" } be_destroy_opt_t; 96.Ft int |
| 91.Fn be_destroy "libbe_handle_t *, const char *, int" ; | 97.Fn be_destroy "libbe_handle_t *" "const char *" "int" ; |
| 92.Pp 93.Ft void | 98.Pp 99.Ft void |
| 94.Fn be_nicenum "uint64_t, char *, size_t" ; | 100.Fn be_nicenum uint64_t" "char *" "size_t" ; |
| 95.Pp 96.\" TODO: Write up of mount options 97.\" typedef enum { 98.\" BE_MNT_FORCE = 1 << 0, 99.\" BE_MNT_DEEP = 1 << 1, 100.\" } be_mount_opt_t; 101.Ft int | 101.Pp 102.\" TODO: Write up of mount options 103.\" typedef enum { 104.\" BE_MNT_FORCE = 1 << 0, 105.\" BE_MNT_DEEP = 1 << 1, 106.\" } be_mount_opt_t; 107.Ft int |
| 102.Fn be_mount "libbe_handle_t *, char *, char *, int" ; | 108.Fn be_mount "libbe_handle_t *" "char *" "char *" "int" ; |
| 103.Pp 104.Ft int | 109.Pp 110.Ft int |
| 105.Fn be_mounted_at "libbe_handle_t *, const char *, nvlist_t" ; | 111.Fn be_mounted_at "libbe_handle_t *" "const char *" "nvlist_t" ; |
| 106.Pp 107.Ft int | 112.Pp 113.Ft int |
| 108.Fn be_unmount "libbe_handle_t *, char *, int" ; | 114.Fn be_unmount "libbe_handle_t *" "char *" "int" ; |
| 109.Pp 110.Ft int 111.Fn libbe_errno "libbe_handle_t *" ; 112.Pp | 115.Pp 116.Ft int 117.Fn libbe_errno "libbe_handle_t *" ; 118.Pp |
| 113.Ft "const char *" Ns | 119.Ft const char * Ns |
| 114.Fn libbe_error_description "libbe_handle_t *" ; 115.Pp 116.Ft void | 120.Fn libbe_error_description "libbe_handle_t *" ; 121.Pp 122.Ft void |
| 117.Fn libbe_print_on_error "libbe_handle_t *, bool" ; | 123.Fn libbe_print_on_error "libbe_handle_t *" "bool" ; |
| 118.Pp 119.Ft int | 124.Pp 125.Ft int |
| 120.Fn be_root_concat "libbe_handle_t *, const char *, char *" ; | 126.Fn be_root_concat "libbe_handle_t *" "const char *" "char *" ; |
| 121.Pp 122.Ft int | 127.Pp 128.Ft int |
| 123.Fn be_validate_name "libbe_handle_t *, const char *" ; | 129.Fn be_validate_name "libbe_handle_t *" "const char *" ; |
| 124.Pp 125.Ft int | 130.Pp 131.Ft int |
| 126.Fn be_validate_snap "libbe_handle_t *, const char *" ; | 132.Fn be_validate_snap "libbe_handle_t *" "const char *" ; |
| 127.Pp 128.Ft bool | 133.Pp 134.Ft bool |
| 129.Fn be_exists "libbe_handle_t *, char *" ; | 135.Fn be_exists "libbe_handle_t *" "char *" ; |
| 130.Pp 131.Ft int | 136.Pp 137.Ft int |
| 132.Fn be_export "libbe_handle_t *, const char *, int fd" ; | 138.Fn be_export "libbe_handle_t *" "const char *" "int fd" ; |
| 133.Pp 134.Ft int | 139.Pp 140.Ft int |
| 135.Fn be_import "libbe_handle_t *, const char *, int fd" ; | 141.Fn be_import "libbe_handle_t *" "const char *" "int fd" ; |
| 136.Pp 137.Ft int 138.Fn be_prop_list_alloc "nvlist_t **" ; 139.Pp 140.Ft int | 142.Pp 143.Ft int 144.Fn be_prop_list_alloc "nvlist_t **" ; 145.Pp 146.Ft int |
| 141.Fn be_get_bootenv_props "libbe_handle_t *, nvlist_t *" ; | 147.Fn be_get_bootenv_props "libbe_handle_t *" "nvlist_t *" ; |
| 142.Pp 143.Ft int | 148.Pp 149.Ft int |
| 144.Fn be_get_dataset_props "libbe_handle_t *, const char *, nvlist_t *" ; | 150.Fn be_get_dataset_props "libbe_handle_t *" "const char *" "nvlist_t *" ; |
| 145.Pp 146.Ft int | 151.Pp 152.Ft int |
| 147.Fn be_get_dataset_snapshots "libbe_handle_t *, const char *, nvlist_t *" ; | 153.Fn be_get_dataset_snapshots "libbe_handle_t *" "const char *" "nvlist_t *" ; |
| 148.Pp 149.Ft void 150.Fn be_prop_list_free "nvlist_t *" ; 151.Sh DIAGNOSTICS 152Upon error, one of the following values will be returned. 153.\" TODO: make each entry on its own line. 154.Bd -ragged -offset indent 155BE_ERR_SUCCESS, --- 13 unchanged lines hidden (view full) --- 169BE_ERR_ZFSOPEN, 170BE_ERR_ZFSCLONE, 171BE_ERR_IO, 172BE_ERR_NOPOOL, 173BE_ERR_NOMEM, 174BE_ERR_UNKNOWN 175.Ed 176.Sh SEE ALSO | 154.Pp 155.Ft void 156.Fn be_prop_list_free "nvlist_t *" ; 157.Sh DIAGNOSTICS 158Upon error, one of the following values will be returned. 159.\" TODO: make each entry on its own line. 160.Bd -ragged -offset indent 161BE_ERR_SUCCESS, --- 13 unchanged lines hidden (view full) --- 175BE_ERR_ZFSOPEN, 176BE_ERR_ZFSCLONE, 177BE_ERR_IO, 178BE_ERR_NOPOOL, 179BE_ERR_NOMEM, 180BE_ERR_UNKNOWN 181.Ed 182.Sh SEE ALSO |
| 177.Xr be 1 , | 183.Xr be 1 |
| 178.Sh HISTORY 179.Nm | 184.Sh HISTORY 185.Nm |
| 180and it's corresponding command, 181.Xr be 3 , | 186and its corresponding command, 187.Xr bectl 8 , |
| 182were written as a 2017 Google Summer of Code project with Allan Jude serving 183as a mentor. 184.\" TODO: update when implementation complete. 185.\" .Sh BUGS | 188were written as a 2017 Google Summer of Code project with Allan Jude serving 189as a mentor. 190.\" TODO: update when implementation complete. 191.\" .Sh BUGS |
| 186 | |