1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
|
.\"
.\" Copyright (c) 2004 Pawel Jakub Dawidek <pjd@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd January 16, 2004
.Dt g_access 9
.Os
.Sh NAME
.Nm g_access
.Nd "control access count between given consumer and its provider"
.Sh SYNOPSIS
.In geom/geom.h
.Ft int
.Fn g_access "struct g_consumer *cp" "int dcr" "int dcw" "int dce"
.Sh DESCRIPTION
The
.Fn g_access
function allows to open/change access to/close the provider which is
attached to the given consumer
.Fa cp .
Arguments
.Fa dcr ,
.Fa dcw ,
.Fa dce
stand for read, write and exclusive access count change.
Read and write access are self explanatory.
Exclusive access count prevents others write access.
Provider's access count is the sum of all attached consumers counts.
After attaching to the provider with
.Fn g_attach
function, one have to use
.Fn g_access
function before starting I/O requests.
.Sh RESTRICTIONS/CONDITIONS
The consumer must be attached.
.Pp
Change cannot result in negative access count.
.Pp
No\-operation is not permitted
.Fa ( dcr
=
.Fa dcw
=
.Fa dce
=
.Va 0 ) .
.Pp
Access method for provider's geom have to be defined (eg. gp->access).
.Pp
The topology lock must be held.
.Sh RETURN VALUES
.Fn g_attach
returns the value 0 if successful; otherwise an error code is returned.
Note, that
.Fn g_access
function cannot failed when arguments
.Fa dcr ,
.Fa dcw
and
.Fa dce
are less than or equal to 0.
.Sh ERRORS
Possible errors:
.Bl -tag -width Er
.It Bq Er EPERM
The function is trying to open with exclusive access count, but provider
is already open for writting.
.It Bq Er EPERM
The function is trying to open for write, but provider is already exclusively
open.
.El
.Pp
Any other error, than can be returned by provider's access method.
.Sh EXAMPLES
Create consumer, attach it to given provider, gain read access and read first
sector.
.Bd -literal -offset indent
void
some_function(struct g_geom *mygeom, struct g_provider *pp)
{
struct g_consumer *cp;
void *ptr;
int error;
g_topology_assert();
/* Create new consumer on 'mygeom' geom. */
cp = g_new_consumer(mygeom);
/* Attach newly created consumer to given provider. */
if (g_attach(cp, pp) != 0) {
g_destroy_consumer(cp);
return;
}
/* Open provider for reading through our consumer. */
error = g_access(cp, 1, 0, 0);
if (error != 0) {
printf("Cannot access provider: %s\\n", error);
g_detach(cp);
g_destroy_consumer(cp);
return;
}
/*
* Don't hold toplogy lock while reading.
*/
g_topology_unlock();
ptr = g_read_data(cp, 0, pp->sectorsize, &error);
if (ptr == NULL)
printf("Error while reading: %d\\n", error);
/*
* Do something useful with data.
*/
g_topology_lock();
/* Disconnect from provider (release access count). */
g_access(cp, -1, 0, 0);
/* Detach from provider. */
g_detach(cp);
/* Destroy consumer. */
g_destroy_consumer(cp);
}
.Ed
.Sh SEE ALSO
.Xr DECLARE_GEOM_CLASS 9 ,
.Xr geom 4 ,
.Xr g_attach 9 ,
.Xr g_bio 9 ,
.Xr g_consumer 9 ,
.Xr g_data 9 ,
.Xr g_event 9 ,
.Xr g_geom 9 ,
.Xr g_provider 9 ,
.Xr g_provider_by_name 9 ,
.Xr g_wither_geom 9
.Sh AUTHORS
.An -nosplit
This manual page was written by
.An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .
|
