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.
35 .Nd "GEOM bio controlling functions"
44 .Fn g_clone_bio "struct bio *bp"
46 .Fn g_duplicate_bio "struct bio *bp"
48 .Fn g_destroy_bio "struct bio *bp"
50 .Fn g_print_bio "struct bio *bp"
54 is used by GEOM to describe I/O requests, its
55 most important fields are described below:
56 .Bl -tag -width ".Va bio_attribute"
59 There are four I/O requests available in GEOM:
60 .Bl -tag -width ".Dv BIO_GETATTR"
66 Indicates that a certain range of data is no longer used and that
67 it can be erased or freed as the underlying technology supports.
68 Technologies like flash adaptation layers can arrange to erase the relevant
69 blocks before they will become reassigned and cryptographic devices may
70 want to fill random bits into the range to reduce the amount of data
73 Inspect and manipulate out-of-band
74 attributes on a particular provider or path.
75 Attributes are named by ascii strings and are stored in the
79 Tells underlying providers to flush their write caches.
83 .Bl -tag -width ".Dv BIO_ERROR"
85 Request failed (error value is stored in
92 Private use by the consumer.
94 Private use by the provider.
98 Pointer to data buffer.
104 Pointer to function which will be called when the request is finished.
106 Private use by the provider.
108 Private use by the provider.
110 Private use by the consumer.
112 Private use by the consumer.
118 Consumer to use for request (attached to provider stored in
120 field) (typically read-only for a class).
122 Destination provider (typically read-only for a class).
124 Request length in bytes.
126 Number of bytes completed, but they may not be completed from
127 the front of the request.
131 clones (typically read-only for a class).
143 function allocates a new, empty
150 but always succeeds (allocates bio with the
156 function allocates a new
158 structure and copies the following fields from the
160 given as an argument to clone:
168 in the clone points to the passed
176 This function should be used for every request which enters through
177 the provider of a particular geom and needs to be scheduled down.
187 Schedule the clone on its own consumer.
193 but always succeeds (allocates bio with the
199 function deallocates and destroys the given
205 function prints information about the given
207 structure (for debugging purposes).
213 functions return a pointer to the allocated
217 if an error occurred.
220 .Dq Dv NULL Ns -transformation ,
221 meaning that an I/O request is cloned and scheduled down without any
223 Let us assume that field
227 contains a consumer attached to the provider we want to operate on.
228 .Bd -literal -offset indent
230 example_start(struct bio *bp)
232 struct example_softc *sc;
235 printf("Request received: ");
239 sc = bp->bio_to->geom->softc;
241 g_io_deliver(bp, ENXIO);
245 /* Let's clone our bio request. */
246 cbp = g_clone_bio(bp);
248 g_io_deliver(bp, ENOMEM);
251 cbp->bio_done = g_std_done; /* Standard 'done' function. */
253 /* Ok, schedule it down. */
255 * The consumer can be obtained from
256 * LIST_FIRST(&bp->bio_to->geom->consumers) as well,
257 * if there is only one in our geom.
259 g_io_request(cbp, sc->ex_consumer);
264 .Xr DECLARE_GEOM_CLASS 9 ,
272 .Xr g_provider_by_name 9 ,
276 This manual page was written by
277 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .