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 ERRORS
  90 Possible errors:
  91 .Bl -tag -width Er
  92 .It Bq Er EPERM
  93 The function is trying to open a provider with an exclusive access count, but
  94 it is already open for writing.
  95 .It Bq Er EPERM
  96 The function is trying to open a provider for writing, but it is already
  97 exclusively open.
  98 .El
  99 .Pp
 100 Any other error that can be returned by the provider's access method.
 101 .Sh EXAMPLES
 102 Create a consumer, attach it to a given provider, gain read access and
 103 read first sector.
 104 .Bd -literal -offset indent
 105 void
 106 some_function(struct g_geom *mygeom, struct g_provider *pp)
 107 {
 108         struct g_consumer *cp;
 109         void *ptr;
 110         int error;
 111
 112         g_topology_assert();
 113
 114         /* Create new consumer on 'mygeom' geom. */
 115         cp = g_new_consumer(mygeom);
 116         /* Attach newly created consumer to given provider. */
 117         if (g_attach(cp, pp) != 0) {
 118                 g_destroy_consumer(cp);
 119                 return;
 120         }
 121         /* Open provider for reading through our consumer. */
 122         error = g_access(cp, 1, 0, 0);
 123         if (error != 0) {
 124                 printf("Cannot access provider: %s\\n", error);
 125                 g_detach(cp);
 126                 g_destroy_consumer(cp);
 127                 return;
 128         }
 129
 130         /*
 131          * Don't hold topology lock while reading.
 132          */
 133         g_topology_unlock();
 134         ptr = g_read_data(cp, 0, pp->sectorsize, &error);
 135         if (ptr == NULL)
 136                 printf("Error while reading: %d\\n", error);
 137         /*
 138          * Do something useful with data.
 139          */
 140         g_topology_lock();
 141
 142         /* Disconnect from provider (release access count). */
 143         g_access(cp, -1, 0, 0);
 144         /* Detach from provider. */
 145         g_detach(cp);
 146         /* Destroy consumer. */
 147         g_destroy_consumer(cp);
 148 }
 149 .Ed
 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 .