192 lines
5.1 KiB
Groff
192 lines
5.1 KiB
Groff
.\"
|
|
.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
|
|
.\"
|
|
.\" Copyright (c) 2017 Kyle Kneitinger
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd August 10, 2018
|
|
.Dt LIBBE 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm libbe
|
|
.Nd library for creating, destroying and modifying ZFS boot environments
|
|
.Sh LIBRARY
|
|
.Lb be
|
|
.Sh SYNOPSIS
|
|
.In be.h
|
|
.Pp
|
|
Function prototypes are given in the
|
|
.Sx FUNCTION OVERVIEW
|
|
section.
|
|
.Pp
|
|
Applications using this interface must be linked with
|
|
.Fl l Ns Ar be
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
interfaces with libzfs to provide a set of functions for various operations
|
|
regarding ZFS boot environments including "deep" boot environments in which
|
|
a boot environments has child datasets.
|
|
.Pp
|
|
A context structure is passed to each function, allowing for a small amount
|
|
of state to be retained, such as errors from previous operations.
|
|
.\" TODO: describe break on err functionality
|
|
.Sh FUNCTION OVERVIEW
|
|
.Ft "libbe_handle_t *" Ns
|
|
.Fn libbe_init void ;
|
|
.Pp
|
|
.Ft void
|
|
.Fn libbe_close "libbe_handle_t *" ;
|
|
.Pp
|
|
.Ft const char * Ns
|
|
.Fn be_active_name "libbe_handle_t *" ;
|
|
.Pp
|
|
.Ft const char * Ns
|
|
.Fn be_active_path "libbe_handle_t *" ;
|
|
.Pp
|
|
.Ft const char * Ns
|
|
.Fn be_nextboot_name "libbe_handle_t *" ;
|
|
.Pp
|
|
.Ft const char * Ns
|
|
.Fn be_nextboot_path "libbe_handle_t *" ;
|
|
.Pp
|
|
.Ft const char * Ns
|
|
.Fn be_root_path "libbe_handle_t *" ;
|
|
.Pp
|
|
.Ft int
|
|
.Fn be_create "libbe_handle_t *" "const char *" ;
|
|
.Pp
|
|
.Ft int
|
|
.Fn be_create_from_existing "libbe_handle_t *" "const char *" "const char *" ;
|
|
.Pp
|
|
.Ft int
|
|
.Fn be_create_from_existing_snap "libbe_handle_t *" "const char *" "const char *" ;
|
|
.Pp
|
|
.Ft int
|
|
.Fn be_rename "libbe_handle_t *" "const char *" "const char *" ;
|
|
.Pp
|
|
.Ft int
|
|
.Fn be_activate "libbe_handle_t *" "const char *" "bool" ;
|
|
.\" TODO: Write up of destroy options
|
|
.\" typedef enum {
|
|
.\" BE_DESTROY_FORCE = 1 << 0,
|
|
.\" } be_destroy_opt_t;
|
|
.Ft int
|
|
.Fn be_destroy "libbe_handle_t *" "const char *" "int" ;
|
|
.Pp
|
|
.Ft void
|
|
.Fn be_nicenum uint64_t" "char *" "size_t" ;
|
|
.Pp
|
|
.\" TODO: Write up of mount options
|
|
.\" typedef enum {
|
|
.\" BE_MNT_FORCE = 1 << 0,
|
|
.\" BE_MNT_DEEP = 1 << 1,
|
|
.\" } be_mount_opt_t;
|
|
.Ft int
|
|
.Fn be_mount "libbe_handle_t *" "char *" "char *" "int" ;
|
|
.Pp
|
|
.Ft int
|
|
.Fn be_mounted_at "libbe_handle_t *" "const char *" "nvlist_t" ;
|
|
.Pp
|
|
.Ft int
|
|
.Fn be_unmount "libbe_handle_t *" "char *" "int" ;
|
|
.Pp
|
|
.Ft int
|
|
.Fn libbe_errno "libbe_handle_t *" ;
|
|
.Pp
|
|
.Ft const char * Ns
|
|
.Fn libbe_error_description "libbe_handle_t *" ;
|
|
.Pp
|
|
.Ft void
|
|
.Fn libbe_print_on_error "libbe_handle_t *" "bool" ;
|
|
.Pp
|
|
.Ft int
|
|
.Fn be_root_concat "libbe_handle_t *" "const char *" "char *" ;
|
|
.Pp
|
|
.Ft int
|
|
.Fn be_validate_name "libbe_handle_t *" "const char *" ;
|
|
.Pp
|
|
.Ft int
|
|
.Fn be_validate_snap "libbe_handle_t *" "const char *" ;
|
|
.Pp
|
|
.Ft bool
|
|
.Fn be_exists "libbe_handle_t *" "char *" ;
|
|
.Pp
|
|
.Ft int
|
|
.Fn be_export "libbe_handle_t *" "const char *" "int fd" ;
|
|
.Pp
|
|
.Ft int
|
|
.Fn be_import "libbe_handle_t *" "const char *" "int fd" ;
|
|
.Pp
|
|
.Ft int
|
|
.Fn be_prop_list_alloc "nvlist_t **" ;
|
|
.Pp
|
|
.Ft int
|
|
.Fn be_get_bootenv_props "libbe_handle_t *" "nvlist_t *" ;
|
|
.Pp
|
|
.Ft int
|
|
.Fn be_get_dataset_props "libbe_handle_t *" "const char *" "nvlist_t *" ;
|
|
.Pp
|
|
.Ft int
|
|
.Fn be_get_dataset_snapshots "libbe_handle_t *" "const char *" "nvlist_t *" ;
|
|
.Pp
|
|
.Ft void
|
|
.Fn be_prop_list_free "nvlist_t *" ;
|
|
.Sh DIAGNOSTICS
|
|
Upon error, one of the following values will be returned.
|
|
.\" TODO: make each entry on its own line.
|
|
.Bd -ragged -offset indent
|
|
BE_ERR_SUCCESS,
|
|
BE_ERR_INVALIDNAME,
|
|
BE_ERR_EXISTS,
|
|
BE_ERR_NOENT,
|
|
BE_ERR_PERMS,
|
|
BE_ERR_DESTROYACT,
|
|
BE_ERR_DESTROYMNT,
|
|
BE_ERR_BADPATH,
|
|
BE_ERR_PATHBUSY,
|
|
BE_ERR_PATHLEN,
|
|
BE_ERR_INVORIGIN,
|
|
BE_ERR_NOORIGIN,
|
|
BE_ERR_MOUNTED,
|
|
BE_ERR_NOMOUNT,
|
|
BE_ERR_ZFSOPEN,
|
|
BE_ERR_ZFSCLONE,
|
|
BE_ERR_IO,
|
|
BE_ERR_NOPOOL,
|
|
BE_ERR_NOMEM,
|
|
BE_ERR_UNKNOWN
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr be 1
|
|
.Sh HISTORY
|
|
.Nm
|
|
and its corresponding command,
|
|
.Xr bectl 8 ,
|
|
were written as a 2017 Google Summer of Code project with Allan Jude serving
|
|
as a mentor.
|
|
.\" TODO: update when implementation complete.
|
|
.\" .Sh BUGS
|