2 .\" Copyright (c) 2004-2006 Pawel Jakub Dawidek <pjd@FreeBSD.org>
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
15 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
16 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
17 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
18 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
19 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
20 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
21 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
22 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
23 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
37 .Nd "GEOM bio controlling functions"
46 .Fn g_clone_bio "struct bio *bp"
48 .Fn g_duplicate_bio "struct bio *bp"
50 .Fn g_destroy_bio "struct bio *bp"
52 .Fn g_format_bio "struct sbuf *sb" "const struct bio *bp"
55 .Fa "struct sbuf *sb" "const char *prefix" "const struct bio *bp"
56 .Fa "const char *fmtsuffix" ...
59 .Fn g_reset_bio "struct bio *bp"
63 is used by GEOM to describe I/O requests, its
64 most important fields are described below:
65 .Bl -tag -width ".Va bio_attribute"
68 There are five I/O requests available in GEOM:
69 .Bl -tag -width ".Dv BIO_GETATTR"
75 Indicates that a certain range of data is no longer used and that
76 it can be erased or freed as the underlying technology supports.
77 Technologies like flash adaptation layers can arrange to erase the relevant
78 blocks before they will become reassigned and cryptographic devices may
79 want to fill random bits into the range to reduce the amount of data
82 Inspect and manipulate out-of-band
83 attributes on a particular provider or path.
84 Attributes are named by ascii strings and are stored in the
88 Tells underlying providers to flush their write caches.
92 .Bl -tag -width ".Dv BIO_ERROR"
94 Request failed (error value is stored in
101 Private use by the consumer.
103 Private use by the provider.
105 Offset into provider.
107 Pointer to data buffer.
113 Pointer to function which will be called when the request is finished.
115 Private use by the provider.
117 Private use by the provider.
119 Private use by the consumer.
121 Private use by the consumer.
127 Consumer to use for request (attached to provider stored in
129 field) (typically read-only for a class).
131 Destination provider (typically read-only for a class).
133 Request length in bytes.
135 Number of bytes completed, but they may not be completed from
136 the front of the request.
140 clones (typically read-only for a class).
152 function allocates a new, empty
159 but always succeeds (allocates bio with the
165 function allocates a new
167 structure and copies the following fields from the
169 given as an argument to clone:
177 in the clone points to the passed
185 This function should be used for every request which enters through
186 the provider of a particular geom and needs to be scheduled down.
196 Schedule the clone on its own consumer.
202 but always succeeds (allocates bio with the
208 function deallocates and destroys the given
214 function prints information about the given
216 structure into the provided
221 function is a convenience wrapper around
223 that can be used for debugging purposes.
226 string, followed by the formatted
232 Any of the prefix or suffix strings may be the empty string.
234 always prints a newline character at the end of the line.
238 function resets the given
240 structure back to its initial state.
242 preserves internal data structures, while setting all
243 user visible fields to their initial values.
252 for multiple transactions,
254 must be called between the transactions in lieu of
256 While not strictly required for a
258 structure created by other means,
260 should be used to initialize it and between transactions.
266 functions return a pointer to the allocated
270 if an error occurred.
273 .Dq Dv NULL Ns -transformation ,
274 meaning that an I/O request is cloned and scheduled down without any
276 Let us assume that field
280 contains a consumer attached to the provider we want to operate on.
281 .Bd -literal -offset indent
283 example_start(struct bio *bp)
285 struct example_softc *sc;
288 g_print_bio("Request received: ", bp, "");
290 sc = bp->bio_to->geom->softc;
292 g_io_deliver(bp, ENXIO);
296 /* Let's clone our bio request. */
297 cbp = g_clone_bio(bp);
299 g_io_deliver(bp, ENOMEM);
302 cbp->bio_done = g_std_done; /* Standard 'done' function. */
304 /* Ok, schedule it down. */
306 * The consumer can be obtained from
307 * LIST_FIRST(&bp->bio_to->geom->consumer) as well,
308 * if there is only one in our geom.
310 g_io_request(cbp, sc->ex_consumer);
315 .Xr DECLARE_GEOM_CLASS 9 ,
323 .Xr g_provider_by_name 9 ,
327 This manual page was written by
328 .An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org .