lib/libbe/libbe.3

   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
   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 AUTHOR 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 AUTHOR 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 .Dd August 10, 2018
  31 .Dt LIBBE 3
  32 .Os
  33 .Sh NAME
  34 .Nm libbe
  35 .Nd library for creating, destroying and modifying ZFS boot environments
  36 .Sh LIBRARY
  37 .Lb be
  38 .Sh SYNOPSIS
  39 .In be.h
  40 .Pp
  41 Function prototypes are given in the
  42 .Sx FUNCTION OVERVIEW
  43 section.
  44 .Pp
  45 Applications using this interface must be linked with
  46 .Fl l Ns Ar be
  47 .Sh DESCRIPTION
  48 .Nm
  49 interfaces with libzfs to provide a set of functions for various operations
  50 regarding ZFS boot environments including "deep" boot environments in which
  51 a boot environments has child datasets.
  52 .Pp
  53 A context structure is passed to each function, allowing for a small amount
  54 of state to be retained, such as errors from previous operations.
  55 .\" TODO: describe break on err functionality
  56 .Sh FUNCTION OVERVIEW
  57 .Ft "libbe_handle_t *" Ns
  58 .Fn libbe_init void ;
  59 .Pp
  60 .Ft void
  61 .Fn libbe_close "libbe_handle_t *" ;
  62 .Pp
  63 .Ft const char * Ns
  64 .Fn be_active_name "libbe_handle_t *" ;
  65 .Pp
  66 .Ft const char * Ns
  67 .Fn be_active_path "libbe_handle_t *" ;
  68 .Pp
  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
  76 .Fn be_root_path "libbe_handle_t *" ;
  77 .Pp
  78 .Ft int
  79 .Fn be_create "libbe_handle_t *" "const char *" ;
  80 .Pp
  81 .Ft int
  82 .Fn be_create_from_existing "libbe_handle_t *" "const char *" "const char *" ;
  83 .Pp
  84 .Ft int
  85 .Fn be_create_from_existing_snap "libbe_handle_t *" "const char *" "const char *" ;
  86 .Pp
  87 .Ft int
  88 .Fn be_rename "libbe_handle_t *" "const char *" "const char *" ;
  89 .Pp
  90 .Ft int
  91 .Fn be_activate "libbe_handle_t *" "const char *" "bool" ;
  92 .\" TODO: Write up of destroy options
  93 .\" typedef enum {
  94 .\"     BE_DESTROY_FORCE = 1 << 0,
  95 .\" } be_destroy_opt_t;
  96 .Ft int
  97 .Fn be_destroy "libbe_handle_t *" "const char *" "int" ;
  98 .Pp
  99 .Ft void
 100 .Fn be_nicenum uint64_t" "char *" "size_t" ;
 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
 108 .Fn be_mount "libbe_handle_t *" "char *" "char *" "int" ;
 109 .Pp
 110 .Ft int
 111 .Fn be_mounted_at "libbe_handle_t *" "const char *" "nvlist_t" ;
 112 .Pp
 113 .Ft int
 114 .Fn be_unmount "libbe_handle_t *" "char *" "int" ;
 115 .Pp
 116 .Ft int
 117 .Fn libbe_errno "libbe_handle_t *" ;
 118 .Pp
 119 .Ft const char * Ns
 120 .Fn libbe_error_description "libbe_handle_t *" ;
 121 .Pp
 122 .Ft void
 123 .Fn libbe_print_on_error "libbe_handle_t *" "bool" ;
 124 .Pp
 125 .Ft int
 126 .Fn be_root_concat "libbe_handle_t *" "const char *" "char *" ;
 127 .Pp
 128 .Ft int
 129 .Fn be_validate_name "libbe_handle_t *" "const char *" ;
 130 .Pp
 131 .Ft int
 132 .Fn be_validate_snap "libbe_handle_t *" "const char *" ;
 133 .Pp
 134 .Ft bool
 135 .Fn be_exists "libbe_handle_t *" "char *" ;
 136 .Pp
 137 .Ft int
 138 .Fn be_export "libbe_handle_t *" "const char *" "int fd" ;
 139 .Pp
 140 .Ft int
 141 .Fn be_import "libbe_handle_t *" "const char *" "int fd" ;
 142 .Pp
 143 .Ft int
 144 .Fn be_prop_list_alloc "nvlist_t **" ;
 145 .Pp
 146 .Ft int
 147 .Fn be_get_bootenv_props "libbe_handle_t *" "nvlist_t *" ;
 148 .Pp
 149 .Ft int
 150 .Fn be_get_dataset_props "libbe_handle_t *" "const char *" "nvlist_t *" ;
 151 .Pp
 152 .Ft int
 153 .Fn be_get_dataset_snapshots "libbe_handle_t *" "const char *" "nvlist_t *" ;
 154 .Pp
 155 .Ft void
 156 .Fn be_prop_list_free "nvlist_t *" ;
 157 .Sh DIAGNOSTICS
 158 Upon error, one of the following values will be returned.
 159 .\" TODO: make each entry on its own line.
 160 .Bd -ragged -offset indent
 161 BE_ERR_SUCCESS,
 162 BE_ERR_INVALIDNAME,
 163 BE_ERR_EXISTS,
 164 BE_ERR_NOENT,
 165 BE_ERR_PERMS,
 166 BE_ERR_DESTROYACT,
 167 BE_ERR_DESTROYMNT,
 168 BE_ERR_BADPATH,
 169 BE_ERR_PATHBUSY,
 170 BE_ERR_PATHLEN,
 171 BE_ERR_INVORIGIN,
 172 BE_ERR_NOORIGIN,
 173 BE_ERR_MOUNTED,
 174 BE_ERR_NOMOUNT,
 175 BE_ERR_ZFSOPEN,
 176 BE_ERR_ZFSCLONE,
 177 BE_ERR_IO,
 178 BE_ERR_NOPOOL,
 179 BE_ERR_NOMEM,
 180 BE_ERR_UNKNOWN
 181 .Ed
 182 .Sh SEE ALSO
 183 .Xr be 1
 184 .Sh HISTORY
 185 .Nm
 186 and its corresponding command,
 187 .Xr bectl 8 ,
 188 were written as a 2017 Google Summer of Code project with Allan Jude serving
 189 as a mentor.
 190 .\" TODO: update when implementation complete.
 191 .\" .Sh BUGS