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