| g_access.9 (127372) | g_access.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_access.9 127372 2004-03-24 14:42:26Z pjd $ | 25.\" $FreeBSD: head/share/man/man9/g_access.9 129381 2004-05-18 11:33:37Z le $ |
| 26.\" 27.Dd January 16, 2004 28.Dt g_access 9 29.Os 30.Sh NAME 31.Nm g_access | 26.\" 27.Dd January 16, 2004 28.Dt g_access 9 29.Os 30.Sh NAME 31.Nm g_access |
| 32.Nd "control access count between given consumer and its provider" | 32.Nd "control access to GEOM consumers and their providers" |
| 33.Sh SYNOPSIS 34.In geom/geom.h 35.Ft int 36.Fn g_access "struct g_consumer *cp" "int dcr" "int dcw" "int dce" 37.Sh DESCRIPTION 38The 39.Fn g_access | 33.Sh SYNOPSIS 34.In geom/geom.h 35.Ft int 36.Fn g_access "struct g_consumer *cp" "int dcr" "int dcw" "int dce" 37.Sh DESCRIPTION 38The 39.Fn g_access |
| 40function allows to open/change access to/close the provider which is 41attached to the given consumer | 40function allows to open, close, and generally change access to the provider 41which is attached to the given consumer |
| 42.Fa cp . | 42.Fa cp . |
| 43Arguments | 43The arguments |
| 44.Fa dcr , 45.Fa dcw , | 44.Fa dcr , 45.Fa dcw , |
| 46and |
|
| 46.Fa dce | 47.Fa dce |
| 47stand for read, write and exclusive access count change. 48Read and write access are self explanatory. 49Exclusive access count prevents others write access. 50Provider's access count is the sum of all attached consumers counts. 51After attaching to the provider with 52.Fn g_attach 53function, one have to use | 48represent relative read, write, and exclusive access count changes. 49Read and write access counts are self explanatory, and 50exclusive access counts deny write access to other interested parties. 51A provider's access count is the sum of the access counts of all 52attached consumers. 53.Pp 54After attaching a consumer to a provider with 55.Fn g_attach , 56the |
| 54.Fn g_access | 57.Fn g_access |
| 55function before starting I/O requests. | 58function has to be called on the consumer before starting I/O requests. |
| 56.Sh RESTRICTIONS/CONDITIONS | 59.Sh RESTRICTIONS/CONDITIONS |
| 57The consumer must be attached. | 60The consumer has to be attached to a provider. |
| 58.Pp | 61.Pp |
| 59Change cannot result in negative access count. | 62The intended change must not result in a negative access count. |
| 60.Pp 61No\-operation is not permitted 62.Fa ( dcr 63= 64.Fa dcw 65= 66.Fa dce 67= 68.Va 0 ) . 69.Pp | 63.Pp 64No\-operation is not permitted 65.Fa ( dcr 66= 67.Fa dcw 68= 69.Fa dce 70= 71.Va 0 ) . 72.Pp |
| 70Access method for provider's geom have to be defined (eg. gp->access). | 73The provider's geom must have an access method defined (eg. gp->access). |
| 71.Pp | 74.Pp |
| 72The topology lock must be held. | 75The topology lock has to be held. |
| 73.Sh RETURN VALUES | 76.Sh RETURN VALUES |
| 74.Fn g_attach 75returns the value 0 if successful; otherwise an error code is returned. 76Note, that | 77The |
| 77.Fn g_access | 78.Fn g_access |
| 78function cannot failed when arguments | 79function returns 0 if successful; otherwise an error code is returned. 80Note that 81.Fn g_access 82cannot fail when the arguments |
| 79.Fa dcr , | 83.Fa dcr , |
| 80.Fa dcw | 84.Fa dcw , |
| 81and 82.Fa dce 83are less than or equal to 0. 84.Sh ERRORS 85Possible errors: 86.Bl -tag -width Er 87.It Bq Er EPERM | 85and 86.Fa dce 87are less than or equal to 0. 88.Sh ERRORS 89Possible errors: 90.Bl -tag -width Er 91.It Bq Er EPERM |
| 88The function is trying to open with exclusive access count, but provider 89is already open for writting. | 92The function is trying to open a provider with an exclusive access count, but 93it is already open for writing. |
| 90.It Bq Er EPERM | 94.It Bq Er EPERM |
| 91The function is trying to open for write, but provider is already exclusively 92open. | 95The function is trying to open a provider for writing, but it is already 96exclusively open. |
| 93.El 94.Pp | 97.El 98.Pp |
| 95Any other error, than can be returned by provider's access method. | 99Any other error that can be returned by the provider's access method. |
| 96.Sh EXAMPLES | 100.Sh EXAMPLES |
| 97Create consumer, attach it to given provider, gain read access and read first 98sector. | 101Create a consumer, attach it to a given provider, gain read access and 102read first sector. |
| 99.Bd -literal -offset indent 100void 101some_function(struct g_geom *mygeom, struct g_provider *pp) 102{ 103 struct g_consumer *cp; 104 void *ptr; 105 int error; 106 --- 11 unchanged lines hidden (view full) --- 118 if (error != 0) { 119 printf("Cannot access provider: %s\\n", error); 120 g_detach(cp); 121 g_destroy_consumer(cp); 122 return; 123 } 124 125 /* | 103.Bd -literal -offset indent 104void 105some_function(struct g_geom *mygeom, struct g_provider *pp) 106{ 107 struct g_consumer *cp; 108 void *ptr; 109 int error; 110 --- 11 unchanged lines hidden (view full) --- 122 if (error != 0) { 123 printf("Cannot access provider: %s\\n", error); 124 g_detach(cp); 125 g_destroy_consumer(cp); 126 return; 127 } 128 129 /* |
| 126 * Don't hold toplogy lock while reading. | 130 * Don't hold topology lock while reading. |
| 127 */ 128 g_topology_unlock(); 129 ptr = g_read_data(cp, 0, pp->sectorsize, &error); 130 if (ptr == NULL) 131 printf("Error while reading: %d\\n", error); 132 /* 133 * Do something useful with data. 134 */ --- 26 unchanged lines hidden --- | 131 */ 132 g_topology_unlock(); 133 ptr = g_read_data(cp, 0, pp->sectorsize, &error); 134 if (ptr == NULL) 135 printf("Error while reading: %d\\n", error); 136 /* 137 * Do something useful with data. 138 */ --- 26 unchanged lines hidden --- |