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