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 December 4, 2010
  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_stripeoffset ,
  54 .Nm g_stripesize ,
  55 .Nm g_flush ,
  56 .Nm g_delete ,
  57 .Nm g_device_path ,
  58 .Nm g_get_ident ,
  59 .Nm g_get_name ,
  60 .Nm g_open_by_ident ,
  61 .Nm g_providername
  62 .Nd userland API library for kernel GEOM subsystem
  63 .Sh LIBRARY
  64 .Lb libgeom
  65 .Sh SYNOPSIS
  66 .In libgeom.h
  67 .Ss "Statistics Functions"
  68 .Ft void
  69 .Fn geom_stats_close void
  70 .Ft int
  71 .Fn geom_stats_open void
  72 .Ft void
  73 .Fn geom_stats_resync void
  74 .Ft "void *"
  75 .Fn geom_stats_snapshot_get void
  76 .Ft void
  77 .Fn geom_stats_snapshot_free "void *arg"
  78 .Ft void
  79 .Fn geom_stats_snapshot_timestamp "void *arg" "struct timespec *tp"
  80 .Ft void
  81 .Fn geom_stats_snapshot_reset "void *arg"
  82 .Ft "struct devstat *"
  83 .Fn geom_stats_snapshot_next "void *arg"
  84 .Ss "Control Functions"
  85 .Ft "struct gctl_req *"
  86 .Fn gctl_get_handle "void"
  87 .Ft void
  88 .Fn gctl_ro_param "struct gctl_req *req" "const char *name" "int len" "const void *value"
  89 .Ft void
  90 .Fn gctl_rw_param "struct gctl_req *req" "const char *name" "int len" "void *value"
  91 .Ft "const char *"
  92 .Fn gctl_issue "struct gctl_req *req"
  93 .Ft void
  94 .Fn gctl_free "struct gctl_req *req"
  95 .Ft void
  96 .Fn gctl_dump "struct gctl_req *req" "FILE *f"
  97 .Ss "Utility Functions"
  98 .Ft int
  99 .Fn g_open "const char *name" "int dowrite"
 100 .Ft int
 101 .Fn g_close "int fd"
 102 .Ft off_t
 103 .Fn g_mediasize "int fd"
 104 .Ft ssize_t
 105 .Fn g_sectorsize "int fd"
 106 .Ft ssize_t
 107 .Fn g_stripeoffset "int fd"
 108 .Ft ssize_t
 109 .Fn g_stripesize "int fd"
 110 .Ft int
 111 .Fn g_flush "int fd"
 112 .Ft int
 113 .Fn g_delete "int fd" "off_t offset" "off_t length"
 114 .Ft "char *"
 115 .Fn g_device_path "const char *devpath"
 116 .Ft int
 117 .Fn g_get_ident "int fd" "char *ident" "size_t size"
 118 .Ft int
 119 .Fn g_get_name "const char *ident" "char *name" "size_t size"
 120 .Ft int
 121 .Fn g_open_by_ident "const char *ident" "int dowrite" "char *name" "size_t size"
 122 .Ft "char *"
 123 .Fn g_providername "int fd"
 124 .Sh DESCRIPTION
 125 The
 126 .Nm geom
 127 library contains the official and publicized API for
 128 interacting with the GEOM subsystem in the kernel.
 129 .Ss "Statistics Functions"
 130 GEOM collects statistics data for all consumers and providers, but does
 131 not perform any normalization or presentation on the raw data, this is
 132 left as an exercise for user-land presentation utilities.
 133 .Pp
 134 The
 135 .Fn geom_stats_open
 136 and
 137 .Fn geom_stats_close
 138 functions open and close the necessary pathways to access the raw
 139 statistics information in the kernel.
 140 These functions are likely to
 141 open one or more files and cache the file descriptors locally.
 142 The
 143 .Fn geom_stats_open
 144 function returns zero on success, and sets
 145 .Va errno
 146 if not.
 147 .Pp
 148 The
 149 .Fn geom_stats_resync
 150 function will check if more statistics collection points have been
 151 added in the kernel since
 152 .Fn geom_stats_open
 153 or the previous call to
 154 .Fn geom_stats_resync .
 155 .Pp
 156 The
 157 .Fn geom_stats_snapshot_get
 158 function
 159 will acquire a snapshot of the raw data from the kernel, and while a
 160 reasonable effort is made to make this snapshot as atomic and consistent
 161 as possible, no guarantee is given that it will actually be so.
 162 The snapshot must be freed again using the
 163 .Fn geom_stats_snapshot_free
 164 function.
 165 The
 166 .Fn geom_stats_snapshot_get
 167 function returns
 168 .Dv NULL
 169 on failure.
 170 .Pp
 171 The
 172 .Fn geom_stats_snapshot_timestamp
 173 function
 174 provides access to the timestamp acquired in the snapshot.
 175 .Pp
 176 The
 177 .Fn geom_stats_snapshot_reset
 178 and
 179 .Fn geom_stats_snapshot_next
 180 functions
 181 provide an iterator over the statistics slots in the snapshot.
 182 The
 183 .Fn geom_stats_snapshot_reset
 184 function
 185 forces the internal pointer in the snapshot back to before the first item.
 186 The
 187 .Fn geom_stats_snapshot_next
 188 function
 189 returns the next item, and
 190 .Dv NULL
 191 if there are no more items in the snapshot.
 192 .Ss "Control Functions"
 193 The
 194 .Fn gctl_*
 195 functions are used to send requests to GEOM classes.
 196 In order for a GEOM
 197 class to actually be able to receive these requests, it must have defined a
 198 "ctlreq" method.
 199 .Pp
 200 A
 201 .Vt "struct gctl_req *" ,
 202 obtained with
 203 .Fn gctl_get_handle ,
 204 can hold any number of parameters, which must be added to it with
 205 .Fn gctl_ro_param
 206 (for read-only parameters) or
 207 .Fn gctl_rw_param
 208 (for read/write parameters).
 209 .Pp
 210 Both
 211 .Fn gctl_ro_param
 212 and
 213 .Fn gctl_rw_param
 214 take a string
 215 .Fa name ,
 216 which is used to identify the parameter, and a
 217 .Fa value ,
 218 which contains, in the read-only case, the data to be passed to the
 219 GEOM class, or, in the read/write case, a pointer to preallocated memory
 220 that the GEOM class should fill with the desired data.
 221 If
 222 .Fa len
 223 is negative, it is assumed that
 224 .Fa value
 225 is an
 226 .Tn ASCII
 227 string and the actual length is taken from the string length of
 228 .Fa value ;
 229 otherwise it must hold the size of
 230 .Fa value .
 231 .Pp
 232 A parameter with a
 233 .Fa name
 234 containing the string
 235 .Qq Li class
 236 is mandatory for each request, and the
 237 corresponding
 238 .Fa value
 239 must hold the name of the GEOM class where the request should be sent to.
 240 .Pp
 241 Also mandatory for each request is a parameter with a
 242 .Fa name
 243 called
 244 .Qq Li verb ,
 245 and the corresponding
 246 .Fa value
 247 needs to hold the command string that the GEOM class should react upon.
 248 .Pp
 249 Once all desired parameters are filled in, the request must be sent to
 250 the GEOM subsystem with
 251 .Fn gctl_issue ,
 252 which returns
 253 .Dv NULL
 254 on success, or a string containing the error message
 255 on failure.
 256 .Pp
 257 After the request is finished, the allocated memory should be released with
 258 .Fn gctl_free .
 259 .Pp
 260 The
 261 .Fn gctl_dump
 262 function
 263 can be used to format the contents of
 264 .Fa req
 265 to the open file handle pointed to by
 266 .Fa f ,
 267 for debugging purposes.
 268 .Pp
 269 Error handling for the control functions is postponed until the call
 270 to
 271 .Fn gctl_issue ,
 272 which returns
 273 .Dv NULL
 274 on success, or an error message corresponding to the
 275 first error which happened.
 276 .Ss "Utility Functions"
 277 The
 278 .Fn g_*
 279 functions are used to communicate with GEOM providers.
 280 .Pp
 281 The
 282 .Fn g_open
 283 function opens the given provider and returns file descriptor number, which can
 284 be used with other functions.
 285 The
 286 .Fa dowrite
 287 argument indicates if operations that modify the provider (like
 288 .Fn g_flush
 289 or
 290 .Fn g_delete )
 291 are going to be called.
 292 .Pp
 293 The
 294 .Fn g_close
 295 function closes the provider.
 296 .Pp
 297 The
 298 .Fn g_mediasize
 299 function returns size of the given provider.
 300 .Pp
 301 The
 302 .Fn g_sectorsize
 303 function returns sector size of the given provider.
 304 .Pp
 305 The
 306 .Fn g_stripeoffset
 307 function returns stripe offset of the given provider.
 308 .Pp
 309 The
 310 .Fn g_stripesize
 311 function returns stripe size of the given provider.
 312 .Pp
 313 The
 314 .Fn g_flush
 315 function sends
 316 .Dv BIO_FLUSH
 317 request to flush write cache of the provider.
 318 .Pp
 319 The
 320 .Fn g_delete
 321 function tells the provider that the given data range is no longer used.
 322 .Pp
 323 The
 324 .Fn g_device_path
 325 function returns the full path to a provider given a partial or full path to the
 326 device node.
 327 If the device can not be found or is not a valid geom provider, NULL is
 328 returned.
 329 .Pp
 330 The
 331 .Fn g_get_ident
 332 function returns provider's fixed and unique identifier.
 333 The
 334 .Fa ident
 335 argument should be at least
 336 .Dv DISK_IDENT_SIZE
 337 big.
 338 .Pp
 339 The
 340 .Fn g_get_name
 341 function returns name of the provider, which identifier is equal to the
 342 .Fa ident
 343 string.
 344 .Pp
 345 The
 346 .Fn g_open_by_ident
 347 function opens provider using its ident, unlike
 348 .Fn g_open
 349 which uses provider's name.
 350 If the
 351 .Fa name
 352 argument is not
 353 .Dv NULL ,
 354 the function will store provider's name there.
 355 .Pp
 356 The
 357 .Fn g_providername
 358 function returns the provider name of an open file descriptor.
 359 If the file descriptor does not point to a valid geom provider, NULL is
 360 returned.
 361 .Pp
 362 All functions except
 363 .Fn g_providername
 364 and
 365 .Fn g_device_path
 366 return a value greater than or equal to
 367 .Va 0
 368 on success or
 369 .Va -1
 370 on failure.
 371 .Sh EXAMPLES
 372 Create a request that is to be sent to the CCD class, and tell
 373 it to destroy a specific geom:
 374 .Bd -literal -offset indent
 375 H = gctl_get_handle();
 376 gctl_ro_param(H, "verb", -1, "destroy geom");
 377 gctl_ro_param(H, "class", -1, "CCD");
 378 sprintf(buf, "ccd%d", ccd);
 379 gctl_ro_param(H, "geom", -1, buf);
 380 errstr = gctl_issue(H);
 381 if (errstr != NULL)
 382     err(1, "could not destroy ccd: %s", errstr);
 383 gctl_free(H);
 384 .Ed
 385 .Sh HISTORY
 386 The
 387 .Nm geom
 388 library appeared in
 389 .Fx 5.1 .
 390 .Sh AUTHORS
 391 .An Poul-Henning Kamp Aq phk@FreeBSD.org
 392 .An Lukas Ertl Aq le@FreeBSD.org
 393 .An Pawel Jakub Dawidek Aq pjd@FreeBSD.org