svn commit: r299312 - head/share/man/man9

[Warner Losh]

Author: imp
Date: Tue May 10 03:57:47 2016
New Revision: 299312
URL: https://svnweb.freebsd.org/changeset/base/299312

Log:
  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@

Modified:
  head/share/man/man9/g_bio.9

Modified: head/share/man/man9/g_bio.9
==============================================================================
--- head/share/man/man9/g_bio.9	Tue May 10 03:42:18 2016	(r299311)
+++ head/share/man/man9/g_bio.9	Tue May 10 03:57:47 2016	(r299312)
@@ -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