Document g_reset_bio(). This is long overdue. g_reset_bio will reset

the bio to a pristine state should you wish to re-use it for another
I/O without freeing it. In the bast, a simple bzero was done to do
this, but that may not be sufficient in the future when the bio may
contain state that's not part of the documented API. Besides, it makes
the code clearer as to the intent...

Noticed by: smh@

1 files changed, 30 insertions, 1 deletions

diff --git a/share/man/man9/g_bio.9 b/share/man/man9/g_bio.9
index 686c0cc8da3e..41d4a24915a2 100644
--- a/share/man/man9/g_bio.9
+++ b/share/man/man9/g_bio.9
@@ -31,7 +31,8 @@
 .Nm g_new_bio ,
 .Nm g_clone_bio ,
 .Nm g_destroy_bio ,
-.Nm g_print_bio
+.Nm g_print_bio ,
+.Nm g_reset_bio
 .Nd "GEOM bio controlling functions"
 .Sh SYNOPSIS
 .In sys/bio.h
@@ -48,6 +49,8 @@
 .Fn g_destroy_bio "struct bio *bp"
 .Ft void
 .Fn g_print_bio "struct bio *bp"
+.Ft void
+.Fn g_reset_bio "struct bio *bp"
 .Sh DESCRIPTION
 A
 .Vt "struct bio"
@@ -205,6 +208,32 @@ The
 function prints information about the given
 .Vt bio
 structure (for debugging purposes).
+.Pp
+The
+.Fn g_reset_bio
+function resets the given
+.Vt bio
+for reuse.
+Prior to
+.Fx 11
+a
+.Vt bio
+was reset for reuse with
+.Xr bzero 3 .
+.Fn g_reset_bio
+preserves internal data structures, while resetting all
+user visible values.
+Its use is required for any
+.Vt bio
+that has been returned by
+.Fn g_new_bio ,
+.Fn g_alloc_bio ,
+.Fn g_clone_bio ,
+or
+.Fn g_duplicate_bio .
+It may be used for a
+.Vt bio
+created in another way, but that is not required.
 .Sh RETURN VALUES
 The
 .Fn g_new_bio