lib/libgeom/libgeom.3

   1 .\" Copyright (c) 2003 Poul-Henning Kamp
   2 .\" Copyright (c) 2007 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 .\" 3. The names of the authors may not be used to endorse or promote
  14 .\"    products derived from this software without specific prior written
  15 .\"    permission.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd May 6, 2007
  32 .Dt LIBGEOM 3
  33 .Os
  34 .Sh NAME
  35 .Nm geom_stats_open ,
  36 .Nm geom_stats_close ,
  37 .Nm geom_stats_resync ,
  38 .Nm geom_stats_snapshot_get ,
  39 .Nm geom_stats_snapshot_free ,
  40 .Nm geom_stats_snapshot_timestamp ,
  41 .Nm geom_stats_snapshot_reset ,
  42 .Nm geom_stats_snapshot_next ,
  43 .Nm gctl_get_handle ,
  44 .Nm gctl_ro_param ,
  45 .Nm gctl_rw_param ,
  46 .Nm gctl_issue ,
  47 .Nm gctl_free ,
  48 .Nm gctl_dump ,
  49 .Nm g_open ,
  50 .Nm g_close ,
  51 .Nm g_mediasize ,
  52 .Nm g_sectorsize ,
  53 .Nm g_flush ,
  54 .Nm g_delete ,
  55 .Nm g_get_ident ,
  56 .Nm g_get_name ,
  57 .Nm g_open_by_ident
  58 .Nd userland API library for kernel GEOM subsystem
  59 .Sh LIBRARY
  60 .Lb libgeom
  61 .Sh SYNOPSIS
  62 .In libgeom.h
  63 .Ss "Statistics Functions"
  64 .Ft void
  65 .Fn geom_stats_close void
  66 .Ft int
  67 .Fn geom_stats_open void
  68 .Ft void
  69 .Fn geom_stats_resync void
  70 .Ft "void *"
  71 .Fn geom_stats_snapshot_get void
  72 .Ft void
  73 .Fn geom_stats_snapshot_free "void *arg"
  74 .Ft void
  75 .Fn geom_stats_snapshot_timestamp "void *arg" "struct timespec *tp"
  76 .Ft void
  77 .Fn geom_stats_snapshot_reset "void *arg"
  78 .Ft "struct devstat *"
  79 .Fn geom_stats_snapshot_next "void *arg"
  80 .Ss "Control Functions"
  81 .Ft "struct gctl_req *"
  82 .Fn gctl_get_handle "void"
  83 .Ft void
  84 .Fn gctl_ro_param "struct gctl_req *req" "const char *name" "int len" "const void *value"
  85 .Ft void
  86 .Fn gctl_rw_param "struct gctl_req *req" "const char *name" "int len" "void *value"
  87 .Ft "const char *"
  88 .Fn gctl_issue "struct gctl_req *req"
  89 .Ft void
  90 .Fn gctl_free "struct gctl_req *req"
  91 .Ft void
  92 .Fn gctl_dump "struct gctl_req *req" "FILE *f"
  93 .Ss "Utility Functions"
  94 .Ft int
  95 .Fn g_open "const char *name" "int write"
  96 .Ft int
  97 .Fn g_close "int fd"
  98 .Ft off_t
  99 .Fn g_mediasize "int fd"
 100 .Ft ssize_t
 101 .Fn g_sectorsize "int fd"
 102 .Ft int
 103 .Fn g_flush "int fd"
 104 .Ft int
 105 .Fn g_delete "int fd" "off_t offset" "off_t length"
 106 .Ft int
 107 .Fn g_get_ident "int fd" "char *ident" "size_t size"
 108 .Ft int
 109 .Fn g_get_name "const char *ident" "char *name" "size_t size"
 110 .Ft int
 111 .Fn g_open_by_ident "const char *ident" "int write" "char *name" "size_t size"
 112 .Sh DESCRIPTION
 113 The
 114 .Nm geom
 115 library contains the official and publicized API for
 116 interacting with the GEOM subsystem in the kernel.
 117 .Ss "Statistics Functions"
 118 GEOM collects statistics data for all consumers and providers, but does
 119 not perform any normalization or presentation on the raw data, this is
 120 left as an exercise for user-land presentation utilities.
 121 .Pp
 122 The
 123 .Fn geom_stats_open
 124 and
 125 .Fn geom_stats_close
 126 functions open and close the necessary pathways to access the raw
 127 statistics information in the kernel.
 128 These functions are likely to
 129 open one or more files and cache the file descriptors locally.
 130 The
 131 .Fn geom_stats_open
 132 function returns zero on success, and sets
 133 .Va errno
 134 if not.
 135 .Pp
 136 The
 137 .Fn geom_stats_resync
 138 function will check if more statistics collection points have been
 139 added in the kernel since
 140 .Fn geom_stats_open
 141 or the previous call to
 142 .Fn geom_stats_resync .
 143 .Pp
 144 The
 145 .Fn geom_stats_snapshot_get
 146 function
 147 will acquire a snapshot of the raw data from the kernel, and while a
 148 reasonable effort is made to make this snapshot as atomic and consistent
 149 as possible, no guarantee is given that it will actually be so.
 150 The snapshot must be freed again using the
 151 .Fn geom_stats_snapshot_free
 152 function.
 153 The
 154 .Fn geom_stats_snapshot_get
 155 function returns
 156 .Dv NULL
 157 on failure.
 158 .Pp
 159 The
 160 .Fn geom_stats_snapshot_timestamp
 161 function
 162 provides access to the timestamp acquired in the snapshot.
 163 .Pp
 164 The
 165 .Fn geom_stats_snapshot_reset
 166 and
 167 .Fn geom_stats_snapshot_next
 168 functions
 169 provide an iterator over the statistics slots in the snapshot.
 170 The
 171 .Fn geom_stats_snapshot_reset
 172 function
 173 forces the internal pointer in the snapshot back to before the first item.
 174 The
 175 .Fn geom_stats_snapshot_next
 176 function
 177 returns the next item, and
 178 .Dv NULL
 179 if there are no more items in the snapshot.
 180 .Ss "Control Functions"
 181 The
 182 .Fn gctl_*
 183 functions are used to send requests to GEOM classes.
 184 In order for a GEOM
 185 class to actually be able to receive these requests, it must have defined a
 186 "ctlreq" method.
 187 .Pp
 188 A
 189 .Vt "struct gctl_req *" ,
 190 obtained with
 191 .Fn gctl_get_handle ,
 192 can hold any number of parameters, which must be added to it with
 193 .Fn gctl_ro_param
 194 (for read-only parameters) or
 195 .Fn gctl_rw_param
 196 (for read/write parameters).
 197 .Pp
 198 Both
 199 .Fn gctl_ro_param
 200 and
 201 .Fn gctl_rw_param
 202 take a string
 203 .Fa name ,
 204 which is used to identify the parameter, and a
 205 .Fa value ,
 206 which contains, in the read-only case, the data to be passed to the
 207 GEOM class, or, in the read/write case, a pointer to preallocated memory
 208 that the GEOM class should fill with the desired data.
 209 If
 210 .Fa len
 211 is negative, it is assumed that
 212 .Fa value
 213 is an
 214 .Tn ASCII
 215 string and the actual length is taken from the string length of
 216 .Fa value ;
 217 otherwise it must hold the size of
 218 .Fa value .
 219 .Pp
 220 A parameter with a
 221 .Fa name
 222 containing the string
 223 .Qq Li class
 224 is mandatory for each request, and the
 225 corresponding
 226 .Fa value
 227 must hold the name of the GEOM class where the request should be sent to.
 228 .Pp
 229 Also mandatory for each request is a parameter with a
 230 .Fa name
 231 called
 232 .Qq Li verb ,
 233 and the corresponding
 234 .Fa value
 235 needs to hold the command string that the GEOM class should react upon.
 236 .Pp
 237 Once all desired parameters are filled in, the request must be sent to
 238 the GEOM subsystem with
 239 .Fn gctl_issue ,
 240 which returns
 241 .Dv NULL
 242 on success, or a string containing the error message
 243 on failure.
 244 .Pp
 245 After the request is finished, the allocated memory should be released with
 246 .Fn gctl_free .
 247 .Pp
 248 The
 249 .Fn gctl_dump
 250 function
 251 can be used to format the contents of
 252 .Fa req
 253 to the open file handle pointed to by
 254 .Fa f ,
 255 for debugging purposes.
 256 .Pp
 257 Error handling for the control functions is postponed until the call
 258 to
 259 .Fn gctl_issue ,
 260 which returns
 261 .Dv NULL
 262 on success, or an error message corresponding to the
 263 first error which happened.
 264 .Ss "Utility Functions"
 265 The
 266 .Fn g_*
 267 functions are used to communicate with GEOM providers.
 268 .Pp
 269 The
 270 .Fn g_open
 271 function opens the given provider and returns file descriptor number, which can
 272 be used with other functions.
 273 The
 274 .Fa write
 275 argument indicates if operations that modify the provider (like
 276 .Fn g_flush
 277 or
 278 .Fn g_delete )
 279 are going to be called.
 280 .Pp
 281 The
 282 .Fn g_close
 283 function closes the provider.
 284 .Pp
 285 The
 286 .Fn g_mediasize
 287 function returns size of the given provider.
 288 .Pp
 289 The
 290 .Fn g_sectorsize
 291 function returns sector size of the given provider.
 292 .Pp
 293 The
 294 .Fn g_flush
 295 function sends
 296 .Dv BIO_FLUSH
 297 request to flush write cache of the provider.
 298 .Pp
 299 The
 300 .Fn g_delete
 301 function tells the provider that the given data range is no longer used.
 302 .Pp
 303 The
 304 .Fn g_get_ident
 305 function returns provider's fixed and unique identifier.
 306 The
 307 .Fa ident
 308 argument should be at least
 309 .Dv DISK_IDENT_SIZE
 310 big.
 311 .Pp
 312 The
 313 .Fn g_get_name
 314 function returns name of the provider, which identifier is equal to the
 315 .Fa ident
 316 string.
 317 .Pp
 318 The
 319 .Fn g_open_by_ident
 320 function opens provider using its ident, unlike
 321 .Fn g_open
 322 which uses provider's name.
 323 If the
 324 .Fa name
 325 argument is not
 326 .Dv NULL ,
 327 the function will store provider's name there.
 328 .Pp
 329 All functions return value greater than or equal to
 330 .Va 0
 331 on success or
 332 .Va -1
 333 on failure.
 334 .Sh EXAMPLES
 335 Create a request that is to be sent to the CCD class, and tell
 336 it to destroy a specific geom:
 337 .Bd -literal -offset indent
 338 H = gctl_get_handle();
 339 gctl_ro_param(H, "verb", -1, "destroy geom");
 340 gctl_ro_param(H, "class", -1, "CCD");
 341 sprintf(buf, "ccd%d", ccd);
 342 gctl_ro_param(H, "geom", -1, buf);
 343 errstr = gctl_issue(H);
 344 if (errstr != NULL)
 345     err(1, "could not destroy ccd: %s", errstr);
 346 gctl_free(H);
 347 .Ed
 348 .Sh SEE ALSO
 349 .Pa http://ezine.daemonnews.org/200308/blueprints.html
 350 .Sh HISTORY
 351 The
 352 .Nm geom
 353 library appeared in
 354 .Fx 5.1 .
 355 .Sh AUTHORS
 356 .An Poul-Henning Kamp Aq phk@FreeBSD.org
 357 .An Lukas Ertl Aq le@FreeBSD.org
 358 .An Pawel Jakub Dawidek pjd@FreeBSD.org