d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

libbe(3)/bectl(8): Make igor and mandoc -Tlint a little happier

Browse Source
This commit is contained in:
kevans 2018-08-11 01:40:24 +00:00
parent 7a884341a8
commit 1c4cf707b2
2 changed files with 54 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
lib/libbe/libbe.3
View File

@ -25,11 +25,6 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" This manual page is based on the mp(3X) manual page from Sun Release
.\" 4.1, dated 7 September 1989. It's an old, crufty, and relatively ugly
.\" manual page, but it does document what appears to be the "traditional"
.\" libmp interface.
.\"
.\" $FreeBSD$
.\"
.Dd August 10, 2018
@ -37,16 +32,19 @@
.Os
.Sh NAME
.Nm libbe
.Nd library for creating, destroying and modifying ZFS boot environments.
.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 main body of the text.
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
.Pp
.Nm
interfaces with libzfs to provide a set of functions for various operations
regarding ZFS boot environments including "deep" boot environments in which
@ -55,43 +53,51 @@ a boot environments has child datasets.
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
.Pp
.Sh FUNCTION OVERVIEW
.Ft "libbe_handle_t *" Ns
.Fn libbe_init "void" ;
.Fn libbe_init void ;
.Pp
.Ft void
.Fn libbe_close "libbe_handle_t *" ;
.Pp
.Ft "const char *" Ns
.Ft const char * Ns
.Fn be_active_name "libbe_handle_t *" ;
.Pp
.Ft "const char *" Ns
.Ft const char * Ns
.Fn be_active_path "libbe_handle_t *" ;
.Pp
.Ft "const char *" Ns
.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 "nvlist_t *" Ns
.Fn libbe_handle_t "libbe_handle_t " ;
.Ft int
.Fn be_create "libbe_handle_t *" "const char *" ;
.Pp
.Ft int
.Fn be_create "libbe_handle_t *, const char *" ;
.Fn be_create_from_existing "libbe_handle_t *" "const char *" "const char *" ;
.Pp
.Ft int
.Fn be_create_from_existing "libbe_handle_t *, const char *, const char *" ;
.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 *" ;
.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" ;
.Fn be_destroy "libbe_handle_t *" "const char *" "int" ;
.Pp
.Ft void
.Fn be_nicenum "uint64_t, char *, size_t" ;
.Fn be_nicenum uint64_t" "char *" "size_t" ;
.Pp
.\" TODO: Write up of mount options
.\" typedef enum {
@ -99,52 +105,52 @@ of state to be retained, such as errors from previous operations.
.\" BE_MNT_DEEP = 1 << 1,
.\" } be_mount_opt_t;
.Ft int
.Fn be_mount "libbe_handle_t *, char *, char *, int" ;
.Fn be_mount "libbe_handle_t *" "char *" "char *" "int" ;
.Pp
.Ft int
.Fn be_mounted_at "libbe_handle_t *, const char *, nvlist_t" ;
.Fn be_mounted_at "libbe_handle_t *" "const char *" "nvlist_t" ;
.Pp
.Ft int
.Fn be_unmount "libbe_handle_t *, char *, int" ;
.Fn be_unmount "libbe_handle_t *" "char *" "int" ;
.Pp
.Ft int
.Fn libbe_errno "libbe_handle_t *" ;
.Pp
.Ft "const char *" Ns
.Ft const char * Ns
.Fn libbe_error_description "libbe_handle_t *" ;
.Pp
.Ft void
.Fn libbe_print_on_error "libbe_handle_t *, bool" ;
.Fn libbe_print_on_error "libbe_handle_t *" "bool" ;
.Pp
.Ft int
.Fn be_root_concat "libbe_handle_t *, const char *, char *" ;
.Fn be_root_concat "libbe_handle_t *" "const char *" "char *" ;
.Pp
.Ft int
.Fn be_validate_name "libbe_handle_t *, const char *" ;
.Fn be_validate_name "libbe_handle_t *" "const char *" ;
.Pp
.Ft int
.Fn be_validate_snap "libbe_handle_t *, const char *" ;
.Fn be_validate_snap "libbe_handle_t *" "const char *" ;
.Pp
.Ft bool
.Fn be_exists "libbe_handle_t *, char *" ;
.Fn be_exists "libbe_handle_t *" "char *" ;
.Pp
.Ft int
.Fn be_export "libbe_handle_t *, const char *, int fd" ;
.Fn be_export "libbe_handle_t *" "const char *" "int fd" ;
.Pp
.Ft int
.Fn be_import "libbe_handle_t *, const char *, int fd" ;
.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 *" ;
.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 *" ;
.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 *" ;
.Fn be_get_dataset_snapshots "libbe_handle_t *" "const char *" "nvlist_t *" ;
.Pp
.Ft void
.Fn be_prop_list_free "nvlist_t *" ;
@ -174,13 +180,12 @@ BE_ERR_NOMEM,
BE_ERR_UNKNOWN
.Ed
.Sh SEE ALSO
.Xr be 1 ,
.Xr be 1
.Sh HISTORY
.Nm
and it's corresponding command,
.Xr be 3 ,
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

30
sbin/bectl/bectl.8
View File

@ -18,9 +18,9 @@
.\"
.\" $FreeBSD$
.\"
.Dd August 5, 2018
.Dd August 10, 2018
.Dt BECTL 8
.Os FreeBSD
.Os
.Sh NAME
.Nm bectl
.Nd Utility to manage Boot Environments on ZFS
@ -76,7 +76,6 @@ command is used to setup and interact with ZFS boot environments, which are boot
.Pp
.Em Boot Environments
allows the system to be upgraded, while preserving the old system environment in a separate ZFS dataset.
.Pp
.Sh COMMANDS
The following commands are supported by
.Nm :
@ -87,10 +86,10 @@ The following commands are supported by
.Pp
Activate the given
.Ar beName
as the default boot filesystem. If the
as the default boot filesystem.
If the
.Op Fl t
flag is given, this takes effect only for the next boot.
.Pp
.It Ic create
.Op Fl r
.Op Fl e Ar nonActiveBe | Fl e Ar beName@snapshot
@ -103,7 +102,6 @@ If the -e param is specified, the new environment will be cloned from the given
If the
.Op Fl r
flag is given, a recursive boot environment will be made.
.Pp
.It Ic create
.Op Fl r
.Ao Ar beName@snapshot Ac
@ -113,7 +111,6 @@ Creates a snapshot of the existing boot environment named
If the
.Op Fl r
flag is given, a recursive boot environment will be made.
.Pp
.It Ic destroy
.Op Fl F
.Ao Ar beName | beName@snapshot Ac
@ -126,7 +123,6 @@ snapshot.
Specifying
.Fl F
will automatically unmount without confirmation.
.Pp
.It Ic jail
.Oo Fl o Ar key Ns = Ns Ar value | Fl u Ar key Oc Ns ...
.Ao Ar jailID | jailName Ac
@ -167,7 +163,7 @@ The following default parameters are provided:
.It Va host.hostname Ns = Ns Ar bootenv
.It Va path
Set to a path in /tmp generated by
.Xr libbe 8 .
.Xr libbe 3 .
.El
.Pp
All default parameters may be overwritten.
@ -188,11 +184,11 @@ If
is used, display the full space usage for each boot environment, assuming all other boot environments were destroyed.
The
.Fl H
option is used for scripting. It does not print headers and separate fields by a single tab instead of arbitrary white space.
option is used for scripting.
It does not print headers and separate fields by a single tab instead of arbitrary white space.
If
.Fl s
is used, display all snapshots as well.
.Pp
.It Ic mount
.Ao Ar beName Ac
.Op mountpoint
@ -201,14 +197,12 @@ Temporarily mount the boot environment.
Mount at the specified
.Ar mountpoint
if provided.
.Pp
.It Ic rename Ao Ar origBeName Ac Ao Ar newBeName Ac
.Pp
Renames the given nonactive
.Ar origBeName
to the given
.Ar newBeName
.Pp
.It Ic unmount
.Op Fl f
.Ao Ar beName Ac
@ -217,17 +211,15 @@ Unmount the given boot environment, if it is mounted.
Specifying
.Fl f
will force the unmount if busy.
.Pp
.It Ic unjail Ao Ar jailID | jailName | beName Ac
.Pp
Destroys the jail created from the given boot environment.
.Pp
.El
.Sh EXAMPLES
.Bl -bullet
.It
To fill in with jail upgrade example when behavior is firm.
.Pp
.El
.Sh SEE ALSO
.Xr jail 8 ,
.Xr zfs 8 ,
@ -241,19 +233,19 @@ and was implemented as a project for the 2017 Summer of Code, along with
.Sh AUTHORS
.Bl -bullet
.It
Kyle Kneitinger (kneitinger)
.An Kyle Kneitinger (kneitinger)
.Ar kyle@kneit.in
.Pp
Creator of
.Nm .
.It
Slawomir Wojciech Wojtczak (vermaden)
.An Slawomir Wojciech Wojtczak (vermaden)
.Ar vermaden@interia.pl
.Pp
Creator and maintainer of
.Xr beadm 1 .
.It
Bryan Drewery (bdrewery)
.An Bryan Drewery (bdrewery)
.Ar bryan@shatow.net
.Pp
Wrote the original