lib/libbe/be.h

   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$
  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
  38 typedef struct libbe_handle libbe_handle_t;
  39
  40 typedef 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 */
  67 libbe_handle_t *libbe_init(const char *root);
  68 void libbe_close(libbe_handle_t *);
  69
  70 /* Bootenv information functions: be_info.c */
  71 const char *be_active_name(libbe_handle_t *);
  72 const char *be_active_path(libbe_handle_t *);
  73 const char *be_nextboot_name(libbe_handle_t *);
  74 const char *be_nextboot_path(libbe_handle_t *);
  75 const char *be_root_path(libbe_handle_t *);
  76
  77 int be_get_bootenv_props(libbe_handle_t *, nvlist_t *);
  78 int be_get_dataset_props(libbe_handle_t *, const char *, nvlist_t *);
  79 int be_get_dataset_snapshots(libbe_handle_t *, const char *, nvlist_t *);
  80 int be_prop_list_alloc(nvlist_t **be_list);
  81 void be_prop_list_free(nvlist_t *be_list);
  82
  83 int be_activate(libbe_handle_t *, const char *, bool);
  84 int be_deactivate(libbe_handle_t *, const char *, bool);
  85
  86 bool be_is_auto_snapshot_name(libbe_handle_t *, const char *);
  87
  88 /* Bootenv creation functions */
  89 int be_create(libbe_handle_t *, const char *);
  90 int be_create_depth(libbe_handle_t *, const char *, const char *, int);
  91 int be_create_from_existing(libbe_handle_t *, const char *, const char *);
  92 int be_create_from_existing_snap(libbe_handle_t *, const char *, const char *);
  93 int be_snapshot(libbe_handle_t *, const char *, const char *, bool, char *);
  94
  95 /* Bootenv manipulation functions */
  96 int be_rename(libbe_handle_t *, const char *, const char *);
  97
  98 /* Bootenv removal functions */
  99
 100 typedef enum {
 101         BE_DESTROY_FORCE        = 1 << 0,
 102         BE_DESTROY_ORIGIN       = 1 << 1,
 103         BE_DESTROY_AUTOORIGIN   = 1 << 2,
 104 } be_destroy_opt_t;
 105
 106 int be_destroy(libbe_handle_t *, const char *, int);
 107
 108 /* Bootenv mounting functions: be_access.c */
 109
 110 typedef enum {
 111         BE_MNT_FORCE            = 1 << 0,
 112         BE_MNT_DEEP             = 1 << 1,
 113 } be_mount_opt_t;
 114
 115 int be_mount(libbe_handle_t *, const char *, const char *, int, char *);
 116 int be_unmount(libbe_handle_t *, const char *, int);
 117 int be_mounted_at(libbe_handle_t *, const char *path, nvlist_t *);
 118
 119 /* Error related functions: be_error.c */
 120 int libbe_errno(libbe_handle_t *);
 121 const char *libbe_error_description(libbe_handle_t *);
 122 void libbe_print_on_error(libbe_handle_t *, bool);
 123
 124 /* Utility Functions */
 125 int be_root_concat(libbe_handle_t *, const char *, char *);
 126 int be_validate_name(libbe_handle_t * __unused, const char *);
 127 int be_validate_snap(libbe_handle_t *, const char *);
 128 int be_exists(libbe_handle_t *, const char *);
 129
 130 int be_export(libbe_handle_t *, const char *, int fd);
 131 int be_import(libbe_handle_t *, const char *, int fd);
 132
 133 #if SOON
 134 int be_add_child(libbe_handle_t *, const char *, bool);
 135 #endif
 136 void be_nicenum(uint64_t num, char *buf, size_t buflen);
 137
 138 #endif  /* _LIBBE_H */