share/man/man9/g_access.9

   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$
  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
  38 The
  39 .Fn g_access
  40 function allows to open, close, and generally change access to the provider
  41 which is attached to the given consumer
  42 .Fa cp .
  43 The arguments
  44 .Fa dcr ,
  45 .Fa dcw ,
  46 and
  47 .Fa dce
  48 represent relative read, write, and exclusive access count changes.
  49 Read and write access counts are self explanatory, and
  50 exclusive access counts deny write access to other interested parties.
  51 A provider's access count is the sum of the access counts of all
  52 attached consumers.
  53 .Pp
  54 After attaching a consumer to a provider with
  55 .Xr g_attach 9 ,
  56 the
  57 .Fn g_access
  58 function has to be called on the consumer before starting I/O requests.
  59 .Sh RESTRICTIONS/CONDITIONS
  60 The consumer has to be attached to a provider.
  61 .Pp
  62 The intended change must not result in a negative access count.
  63 .Pp
  64 No-operation is not permitted
  65 .Fa ( dcr
  66 =
  67 .Fa dcw
  68 =
  69 .Fa dce
  70 =
  71 .Li 0 ) .
  72 .Pp
  73 The provider's geom must have an access method defined (e.g.,
  74 .Va gp->access ) .
  75 .Pp
  76 The topology lock has to be held.
  77 .Sh RETURN VALUES
  78 The
  79 .Fn g_access
  80 function returns 0 if successful; otherwise an error code is returned.
  81 Note that
  82 .Fn g_access
  83 cannot fail when the arguments
  84 .Fa dcr ,
  85 .Fa dcw ,
  86 and
  87 .Fa dce
  88 are less than or equal to 0.
  89 .Sh EXAMPLES
  90 Create a consumer, attach it to a given provider, gain read access and
  91 read first sector.
  92 .Bd -literal -offset indent
  93 void
  94 some_function(struct g_geom *mygeom, struct g_provider *pp)
  95 {
  96         struct g_consumer *cp;
  97         void *ptr;
  98         int error;
  99
 100         g_topology_assert();
 101
 102         /* Create new consumer on 'mygeom' geom. */
 103         cp = g_new_consumer(mygeom);
 104         /* Attach newly created consumer to given provider. */
 105         if (g_attach(cp, pp) != 0) {
 106                 g_destroy_consumer(cp);
 107                 return;
 108         }
 109         /* Open provider for reading through our consumer. */
 110         error = g_access(cp, 1, 0, 0);
 111         if (error != 0) {
 112                 printf("Cannot access provider: %s\\n", error);
 113                 g_detach(cp);
 114                 g_destroy_consumer(cp);
 115                 return;
 116         }
 117
 118         /*
 119          * Don't hold topology lock while reading.
 120          */
 121         g_topology_unlock();
 122         ptr = g_read_data(cp, 0, pp->sectorsize, &error);
 123         if (ptr == NULL)
 124                 printf("Error while reading: %d\\n", error);
 125         /*
 126          * Do something useful with data.
 127          */
 128         g_topology_lock();
 129
 130         /* Disconnect from provider (release access count). */
 131         g_access(cp, -1, 0, 0);
 132         /* Detach from provider. */
 133         g_detach(cp);
 134         /* Destroy consumer. */
 135         g_destroy_consumer(cp);
 136 }
 137 .Ed
 138 .Sh ERRORS
 139 Possible errors:
 140 .Bl -tag -width Er
 141 .It Bq Er EPERM
 142 The function is trying to open a provider with an exclusive access count, but
 143 it is already open for writing.
 144 .It Bq Er EPERM
 145 The function is trying to open a provider for writing, but it is already
 146 exclusively open.
 147 .El
 148 .Pp
 149 Any other error that can be returned by the provider's access method.
 150 .Sh SEE ALSO
 151 .Xr geom 4 ,
 152 .Xr DECLARE_GEOM_CLASS 9 ,
 153 .Xr g_attach 9 ,
 154 .Xr g_bio 9 ,
 155 .Xr g_consumer 9 ,
 156 .Xr g_data 9 ,
 157 .Xr g_event 9 ,
 158 .Xr g_geom 9 ,
 159 .Xr g_provider 9 ,
 160 .Xr g_provider_by_name 9 ,
 161 .Xr g_wither_geom 9
 162 .Sh AUTHORS
 163 .An -nosplit
 164 This manual page was written by
 165 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org .