| g_bio.9 (126861) | g_bio.9 (129381) |
|---|---|
| 1.\" 2.\" Copyright (c) 2004 Pawel Jakub Dawidek <pjd@FreeBSD.org> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright --- 8 unchanged lines hidden (view full) --- 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. 24.\" | 1.\" 2.\" Copyright (c) 2004 Pawel Jakub Dawidek <pjd@FreeBSD.org> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright --- 8 unchanged lines hidden (view full) --- 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. 24.\" |
| 25.\" $FreeBSD: head/share/man/man9/g_bio.9 126861 2004-03-11 19:53:22Z pjd $ | 25.\" $FreeBSD: head/share/man/man9/g_bio.9 129381 2004-05-18 11:33:37Z le $ |
| 26.\" 27.Dd January 16, 2004 28.Dt g_bio 9 29.Os 30.Sh NAME 31.Nm g_new_bio , 32.Nm g_clone_bio , 33.Nm g_destroy_bio , 34.Nm g_print_bio | 26.\" 27.Dd January 16, 2004 28.Dt g_bio 9 29.Os 30.Sh NAME 31.Nm g_new_bio , 32.Nm g_clone_bio , 33.Nm g_destroy_bio , 34.Nm g_print_bio |
| 35.Nd "bio controlling functions" | 35.Nd "GEOM bio controlling functions" |
| 36.Sh SYNOPSIS 37.In sys/bio.h 38.In geom/geom.h 39.Ft "struct bio *" 40.Fn g_new_bio void 41.Ft "struct bio *" 42.Fn g_clone_bio "struct bio *bp" 43.Ft void 44.Fn g_destroy_bio "struct bio *bp" 45.Ft void 46.Fn g_print_bio "struct bio *bp" 47.Sh DESCRIPTION | 36.Sh SYNOPSIS 37.In sys/bio.h 38.In geom/geom.h 39.Ft "struct bio *" 40.Fn g_new_bio void 41.Ft "struct bio *" 42.Fn g_clone_bio "struct bio *bp" 43.Ft void 44.Fn g_destroy_bio "struct bio *bp" 45.Ft void 46.Fn g_print_bio "struct bio *bp" 47.Sh DESCRIPTION |
| 48The 49.Fa bio 50structure is used by GEOM to describe I/O requests. 51Most important fields of | 48A |
| 52.Fa struct bio | 49.Fa struct bio |
| 53are described below: | 50is used by GEOM to describe I/O requests, its 51most important fields are described below: |
| 54.Bl -tag -width ".Va bio_attribute" 55.It Va bio_cmd | 52.Bl -tag -width ".Va bio_attribute" 53.It Va bio_cmd |
| 56I/O request number. | 54I/O request command. |
| 57There are four I/O requests available in GEOM: 58.Bl -tag -width BIO_GETATTR 59.It Dv BIO_READ | 55There are four I/O requests available in GEOM: 56.Bl -tag -width BIO_GETATTR 57.It Dv BIO_READ |
| 60Self explanatory. | 58A read request. |
| 61.It Dv BIO_WRITE | 59.It Dv BIO_WRITE |
| 62Self explanatory. | 60A write request. |
| 63.It Dv BIO_DELETE | 61.It Dv BIO_DELETE |
| 64Delete indicates that a certain range of data is no longer used and that | 62Indicates that a certain range of data is no longer used and that |
| 65it can be erased or freed as the underlying technology supports. 66Technologies like flash adaptation layers can arrange to erase the relevant 67blocks before they will become reassigned and cryptographic devices may 68want to fill random bits into the range to reduce the amount of data 69available for attack. 70.It Dv BIO_GETATTR | 63it can be erased or freed as the underlying technology supports. 64Technologies like flash adaptation layers can arrange to erase the relevant 65blocks before they will become reassigned and cryptographic devices may 66want to fill random bits into the range to reduce the amount of data 67available for attack. 68.It Dv BIO_GETATTR |
| 71Get attribute supports inspection and manipulation of out\-of\-band | 69Inspect and manipulate out\-of\-band |
| 72attributes on a particular provider or path. 73Attributes are named by ascii strings and are stored in the 74.Va bio_attribute 75field. 76.El 77.It Va bio_offset 78Offset into provider. 79.It Va bio_data 80Pointer to data buffer. 81.It Va bio_flags 82Available flags: 83.Bl -tag -width BIO_GETATTR 84.It Dv BIO_ERROR 85Request failed (error value is stored in | 70attributes on a particular provider or path. 71Attributes are named by ascii strings and are stored in the 72.Va bio_attribute 73field. 74.El 75.It Va bio_offset 76Offset into provider. 77.It Va bio_data 78Pointer to data buffer. 79.It Va bio_flags 80Available flags: 81.Bl -tag -width BIO_GETATTR 82.It Dv BIO_ERROR 83Request failed (error value is stored in |
| 86.Va bio_error ) 87field. | 84.Va bio_error 85field). |
| 88.It Dv BIO_DONE 89Request finished. 90.It Dv BIO_FLAG1 91Avaliable for private use. 92.It Dv BIO_FLAG2 93Avaliable for private use. 94.El 95.It Va bio_error 96Error value when BIO_ERROR is set. 97.It Va bio_done | 86.It Dv BIO_DONE 87Request finished. 88.It Dv BIO_FLAG1 89Avaliable for private use. 90.It Dv BIO_FLAG2 91Avaliable for private use. 92.El 93.It Va bio_error 94Error value when BIO_ERROR is set. 95.It Va bio_done |
| 98Pointer to function which will be called on request finish. | 96Pointer to function which will be called when the request is finished. |
| 99.It Va bio_driver1 100Private use by the callee (ie: the provider). 101.It Va bio_driver2 102Private use by the callee (ie: the provider). 103.It Va bio_caller1 104Private use by the caller (ie: the consumer). 105.It Va bio_caller2 106Private use by the caller (ie: the consumer). --- 23 unchanged lines hidden (view full) --- 130function allocates a new, empty 131.Vt bio 132structure. 133.Pp 134The 135.Fn g_clone_bio 136function allocates a new 137.Vt bio | 97.It Va bio_driver1 98Private use by the callee (ie: the provider). 99.It Va bio_driver2 100Private use by the callee (ie: the provider). 101.It Va bio_caller1 102Private use by the caller (ie: the consumer). 103.It Va bio_caller2 104Private use by the caller (ie: the consumer). --- 23 unchanged lines hidden (view full) --- 128function allocates a new, empty 129.Vt bio 130structure. 131.Pp 132The 133.Fn g_clone_bio 134function allocates a new 135.Vt bio |
| 138structure and copies those fields from the | 136structure and copies the following fields from the |
| 139.Vt bio | 137.Vt bio |
| 140structure given as an argument to clone: | 138given as an argument to clone: |
| 141.Va bio_cmd , 142.Va bio_length , 143.Va bio_offset , 144.Va bio_data , 145.Va bio_attribute . 146The field 147.Va bio_parent | 139.Va bio_cmd , 140.Va bio_length , 141.Va bio_offset , 142.Va bio_data , 143.Va bio_attribute . 144The field 145.Va bio_parent |
| 148in clone is set to source | 146in the clone points to the passed |
| 149.Vt bio 150and the field 151.Va bio_children | 147.Vt bio 148and the field 149.Va bio_children |
| 152in parent is increased. | 150in the passed 151.Vt bio 152is incremented. |
| 153.Pp 154This function should be used for every request which enters through 155the provider of a particular geom and needs to be scheduled down. 156Proper order is: 157.Pp 158.Bl -enum -compact 159.It | 153.Pp 154This function should be used for every request which enters through 155the provider of a particular geom and needs to be scheduled down. 156Proper order is: 157.Pp 158.Bl -enum -compact 159.It |
| 160Clone | 160Clone the received |
| 161.Vt "struct bio" . 162.It 163Modify the clone. 164.It 165Schedule the clone on its own consumer. 166.El 167.Pp 168The 169.Fn g_destroy_bio | 161.Vt "struct bio" . 162.It 163Modify the clone. 164.It 165Schedule the clone on its own consumer. 166.El 167.Pp 168The 169.Fn g_destroy_bio |
| 170function kills the given | 170function deallocates and destroys the given |
| 171.Vt bio 172structure. 173.Pp 174The 175.Fn g_print_bio | 171.Vt bio 172structure. 173.Pp 174The 175.Fn g_print_bio |
| 176function prints informations about given | 176function prints information about the given |
| 177.Vt bio | 177.Vt bio |
| 178structure. | 178structure (for debugging purposes). 179.Sh RETURN VALUES 180The 181.Fn g_new_bio 182and 183.Fn g_clone_bio 184functions return a pointer to the allocated 185.Vt bio , 186or NULL if an error occurred. |
| 179.Sh EXAMPLES 180Implementation of 181.Dq Dv NULL Ns \-transformation , 182meaning that an I/O request is cloned and scheduled down without any 183modifications. 184Let's assume that field 185.Va ex_consumer 186in structure --- 52 unchanged lines hidden --- | 187.Sh EXAMPLES 188Implementation of 189.Dq Dv NULL Ns \-transformation , 190meaning that an I/O request is cloned and scheduled down without any 191modifications. 192Let's assume that field 193.Va ex_consumer 194in structure --- 52 unchanged lines hidden --- |