From owner-svn-src-projects@freebsd.org Sat Aug 11 01:40:26 2018 Return-Path: Delivered-To: svn-src-projects@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 28E81105554F for ; Sat, 11 Aug 2018 01:40:26 +0000 (UTC) (envelope-from kevans@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id C04C384E92; Sat, 11 Aug 2018 01:40:25 +0000 (UTC) (envelope-from kevans@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 9CE4510622; Sat, 11 Aug 2018 01:40:25 +0000 (UTC) (envelope-from kevans@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id w7B1ePNl056104; Sat, 11 Aug 2018 01:40:25 GMT (envelope-from kevans@FreeBSD.org) Received: (from kevans@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id w7B1ePBY056103; Sat, 11 Aug 2018 01:40:25 GMT (envelope-from kevans@FreeBSD.org) Message-Id: <201808110140.w7B1ePBY056103@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: kevans set sender to kevans@FreeBSD.org using -f From: Kyle Evans Date: Sat, 11 Aug 2018 01:40:25 +0000 (UTC) To: src-committers@freebsd.org, svn-src-projects@freebsd.org Subject: svn commit: r337598 - in projects/bectl: lib/libbe sbin/bectl X-SVN-Group: projects X-SVN-Commit-Author: kevans X-SVN-Commit-Paths: in projects/bectl: lib/libbe sbin/bectl X-SVN-Commit-Revision: 337598 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-projects@freebsd.org X-Mailman-Version: 2.1.27 Precedence: list List-Id: "SVN commit messages for the src " projects" tree" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 11 Aug 2018 01:40:26 -0000 Author: kevans Date: Sat Aug 11 01:40:24 2018 New Revision: 337598 URL: https://svnweb.freebsd.org/changeset/base/337598 Log: libbe(3)/bectl(8): Make igor and mandoc -Tlint a little happier Modified: projects/bectl/lib/libbe/libbe.3 projects/bectl/sbin/bectl/bectl.8 Modified: projects/bectl/lib/libbe/libbe.3 ============================================================================== --- projects/bectl/lib/libbe/libbe.3 Sat Aug 11 01:05:44 2018 (r337597) +++ projects/bectl/lib/libbe/libbe.3 Sat Aug 11 01:40:24 2018 (r337598) @@ -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 .\" 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 - Modified: projects/bectl/sbin/bectl/bectl.8 ============================================================================== --- projects/bectl/sbin/bectl/bectl.8 Sat Aug 11 01:05:44 2018 (r337597) +++ projects/bectl/sbin/bectl/bectl.8 Sat Aug 11 01:40:24 2018 (r337598) @@ -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 en .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 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 na 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 o .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