Deleted Added
sdiff udiff text old ( 129381 ) new ( 131530 )
full compact
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
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.
13.\"
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.
24.\"
25.\" $FreeBSD: head/share/man/man9/g_access.9 131530 2004-07-03 18:29:24Z ru $
26.\"
27.Dd January 16, 2004
28.Dt g_access 9
29.Os
30.Sh NAME
31.Nm g_access
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
40function allows to open, close, and generally change access to the provider
41which is attached to the given consumer
42.Fa cp .
43The arguments
44.Fa dcr ,
45.Fa dcw ,
46and
47.Fa dce
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
57.Fn g_access
58function has to be called on the consumer before starting I/O requests.
59.Sh RESTRICTIONS/CONDITIONS
60The consumer has to be attached to a provider.
61.Pp
62The intended change must not result in a negative access count.
63.Pp
64No\-operation is not permitted
65.Fa ( dcr
66=
67.Fa dcw
68=
69.Fa dce
70=
71.Va 0 ) .
72.Pp
73The provider's geom must have an access method defined (e.g.\& gp->access).
74.Pp
75The topology lock has to be held.
76.Sh RETURN VALUES
77The
78.Fn g_access
79function returns 0 if successful; otherwise an error code is returned.
80Note that
81.Fn g_access
82cannot fail when the arguments
83.Fa dcr ,
84.Fa dcw ,
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
92The function is trying to open a provider with an exclusive access count, but
93it is already open for writing.
94.It Bq Er EPERM
95The function is trying to open a provider for writing, but it is already
96exclusively open.
97.El
98.Pp
99Any other error that can be returned by the provider's access method.
100.Sh EXAMPLES
101Create a consumer, attach it to a given provider, gain read access and
102read first sector.
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
111 g_topology_assert();
112
113 /* Create new consumer on 'mygeom' geom. */
114 cp = g_new_consumer(mygeom);
115 /* Attach newly created consumer to given provider. */
116 if (g_attach(cp, pp) != 0) {
117 g_destroy_consumer(cp);
118 return;
119 }
120 /* Open provider for reading through our consumer. */
121 error = g_access(cp, 1, 0, 0);
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 /*
130 * Don't hold topology lock while reading.
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 */
139 g_topology_lock();
140
141 /* Disconnect from provider (release access count). */
142 g_access(cp, -1, 0, 0);
143 /* Detach from provider. */
144 g_detach(cp);
145 /* Destroy consumer. */
146 g_destroy_consumer(cp);
147}
148.Ed
149.Sh SEE ALSO
150.Xr DECLARE_GEOM_CLASS 9 ,
151.Xr geom 4 ,
152.Xr g_attach 9 ,
153.Xr g_bio 9 ,
154.Xr g_consumer 9 ,
155.Xr g_data 9 ,
156.Xr g_event 9 ,
157.Xr g_geom 9 ,
158.Xr g_provider 9 ,
159.Xr g_provider_by_name 9 ,
160.Xr g_wither_geom 9
161.Sh AUTHORS
162.An -nosplit
163This manual page was written by
164.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .