lib/libmt/mt.3

   1 .\"
   2 .\" Copyright (c) 2013, 2015 Spectra Logic Corporation
   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 .\"    without modification.
  11 .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer
  12 .\"    substantially similar to the "NO WARRANTY" disclaimer below
  13 .\"    ("Disclaimer") and any redistribution must be conditioned upon
  14 .\"    including a substantially similar Disclaimer requirement for further
  15 .\"    binary redistribution.
  16 .\"
  17 .\" NO WARRANTY
  18 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19 .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
  21 .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22 .\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  26 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  27 .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGES.
  29 .\"
  30 .\" Authors: Ken Merry           (Spectra Logic Corporation)
  31 .\"
  32 .\" $FreeBSD$
  33 .\"
  34 .Dd February 13, 2015
  35 .Dt MT 3
  36 .Os
  37 .Sh NAME
  38 .Nm mt_start_element ,
  39 .Nm mt_end_element ,
  40 .Nm mt_char_handler ,
  41 .Nm mt_status_tree_sbuf ,
  42 .Nm mt_status_tree_print ,
  43 .Nm mt_status_entry_free ,
  44 .Nm mt_status_free ,
  45 .Nm mt_entry_sbuf ,
  46 .Nm mt_param_parent_print ,
  47 .Nm mt_param_entry_print ,
  48 .Nm mt_protect_print ,
  49 .Nm mt_param_list ,
  50 .Nm mt_density_name ,
  51 .Nm mt_density_bp ,
  52 .Nm mt_density_num ,
  53 .Nm mt_get_xml_str ,
  54 .Nm mt_get_status
  55 .Nd Magnetic Tape library
  56 .Sh LIBRARY
  57 .Lb libmt
  58 .Sh SYNOPSIS
  59 .In sys/sbuf.h
  60 .In bsdxml.h
  61 .In mtlib.h
  62 .Ft void
  63 .Fo mt_start_element
  64 .Fa "void *user_data"
  65 .Fa "const char *name"
  66 .Fa "const char **attr"
  67 .Fc
  68 .Ft void
  69 .Fo mt_end_element
  70 .Fa "void *user_data"
  71 .Fa "const char *name"
  72 .Fc
  73 .Ft void
  74 .Fo mt_char_handler
  75 .Fa "void *user_data"
  76 .Fa "const XML_Char *str"
  77 .Fa "int len"
  78 .Fc
  79 .Ft void
  80 .Fo mt_status_tree_sbuf
  81 .Fa "struct sbuf *sb"
  82 .Fa "struct mt_status_entry *entry"
  83 .Fa "int indent"
  84 .Fa "void (*sbuf_func)(struct sbuf *sb, struct mt_status_entry *entry, void *arg)"
  85 .Fa "void *arg"
  86 .Fc
  87 .Ft void
  88 .Fo mt_status_tree_print
  89 .Fa "struct mt_status_entry *entry"
  90 .Fa "int indent"
  91 .Fa "void (*print_func)(struct mt_status_entry *entry, void *arg)"
  92 .Fa "void *arg"
  93 .Fc
  94 .Ft "struct mt_status_entry *"
  95 .Fo mt_entry_find
  96 .Fa "struct mt_status_entry *entry"
  97 .Fa "char *name"
  98 .Fc
  99 .Ft "struct mt_status_entry *"
 100 .Fo mt_status_entry_find
 101 .Fa "struct mt_status_data *status_data"
 102 .Fa "char *name"
 103 .Fc
 104 .Ft void
 105 .Fo mt_status_entry_free
 106 .Fa "struct mt_status_entry *entry)"
 107 .Fc
 108 .Ft void
 109 .Fo mt_status_free
 110 .Fa "struct mt_status_data *status_data"
 111 .Fc
 112 .Ft void
 113 .Fo mt_entry_sbuf
 114 .Fa "struct sbuf *sb"
 115 .Fa "struct mt_status_entry *entry"
 116 .Fa "char *fmt"
 117 .Fc
 118 .Ft void
 119 .Fo mt_param_parent_sbuf
 120 .Fa "struct sbuf *sb"
 121 .Fa "struct mt_status_entry *entry"
 122 .Fa "struct mt_print_params *print_params"
 123 .Fc
 124 .Ft void
 125 .Fo mt_param_parent_print
 126 .Fa "struct mt_status_entry *entry"
 127 .Fa "struct mt_print_params *print_params"
 128 .Fc
 129 .Ft void
 130 .Fo mt_param_entry_sbuf
 131 .Fa "struct sbuf *sb"
 132 .Fa "struct mt_status_entry *entry"
 133 .Fa "void *arg"
 134 .Fc
 135 .Ft void
 136 .Fo mt_param_entry_print
 137 .Fa "struct mt_status_entry *entry"
 138 .Fa "void *arg"
 139 .Fc
 140 .Ft int
 141 .Fo mt_protect_print
 142 .Fa "struct mt_status_data *status_data"
 143 .Fa "int verbose"
 144 .Fc
 145 .Ft int
 146 .Fo mt_param_list
 147 .Fa "struct mt_status_data *status_data"
 148 .Fa "char *param_name"
 149 .Fa "int quiet"
 150 .Fc
 151 .Ft "const char *"
 152 .Fo mt_density_name
 153 .Fa "int density_num"
 154 .Fc
 155 .Ft int
 156 .Fo mt_density_bp
 157 .Fa "int density_num"
 158 .Fa "int bpi"
 159 .Fc
 160 .Ft int
 161 .Fo mt_density_num
 162 .Fa "const char *density_name"
 163 .Fc
 164 .Ft int
 165 .Fo mt_get_status
 166 .Fa "char *xml_str"
 167 .Fa "struct mt_status_data *status_data"
 168 .Fc
 169 .Sh DESCRIPTION
 170 The MT library consists of a number of functions designed to aid in
 171 interacting with the
 172 .Xr sa 4
 173 driver.
 174 The
 175 .Xr sa 4
 176 driver returns some status data as XML-formatted strings, and
 177 the primary purpose of this library is to make it easier for the
 178 software developer to parse those strings and extract the status values.
 179 .Pp
 180 The
 181 .Fn mt_start_element ,
 182 .Fn mt_end_element ,
 183 and
 184 .Fn mt_char_handler
 185 functions are designed to work with the
 186 .Xr libbsdxml 3
 187 library, which is an XML parsing library.
 188 The user data for the XML parser should be set with
 189 .Fn XML_SetUserData
 190 to a zeroed struct
 191 mt_status_data with the entries list initialized.
 192 The element handlers for the XML parser should be set to
 193 .Fn mt_start_element
 194 and
 195 .Fn mt_end_element
 196 with
 197 .Fn XML_SetElementHandler .
 198 The character data handler should be set to
 199 .Fn mt_char_handler
 200 with the
 201 .Fn XML_SetCharacterDataHandler
 202 function.
 203 The error member of the status_data structure will be set to 0 if parsing
 204 is successful, and non-zero if parsing failed.
 205 In the event of a failure, the error_str member will contain an error
 206 message describing the failure.
 207 These functions will build a tree of tape driver status data that can be
 208 searched and printed using the other functions in this library.
 209 .Pp
 210 .Fn mt_status_tree_sbuf
 211 takes the root node of a tree of
 212 .Xr sa 4
 213 driver status information, and displays it in an
 214 .Xr sbuf 9 .
 215 The
 216 .Ar sb
 217 argument is the destination sbuf.
 218 The
 219 .Ar entry
 220 argument is the root of the tree.
 221 The
 222 .Ar indent
 223 argument is the number of characters to indent the output.
 224 Each recursive call to
 225 .Fn mt_status_tree_sbuf
 226 will have the indent level incremented by 2.
 227 The
 228 .Ar sbuf_func
 229 argument is for a user-supplied alternate printing function.
 230 If it is non-NULL, it will be called instead of the default output printing
 231 code.
 232 The
 233 .Ar arg
 234 argument is an argument for the
 235 .Ar sbuf_func
 236 function.
 237 .Pp
 238 The
 239 .Fn mt_status_tree_print
 240 function is the same as the
 241 .Fn mt_status_tree_sbuf
 242 function, except that the tree is printed to standard out instead of to a
 243 sbuf.
 244 .Pp
 245 The
 246 .Fn mt_entry_find
 247 function returns the first entry in the tree starting at
 248 .Ar entry
 249 that matches
 250 .Ar name .
 251 The supplied node name can be a single level name like "foo", or it can
 252 specify mulitple node names that must be matched, for instance "foo.bar.baz".
 253 In the case of a single level name, it will match any node beneath
 254 .Ar entry
 255 that matches
 256 .Ar name .
 257 In the case of a multi-level name like "foo.bar.baz", it will return the
 258 first entry named "baz" whose immediate parent is "bar" and where the
 259 parent of "bar" is named "foo".
 260 .Pp
 261 The
 262 .Fn mt_status_entry_find
 263 is the same as
 264 .Fn mt_entry_find ,
 265 except that it operates on the top level mt_status_data and all
 266 mt_status_entry nodes below it instead of just an mt_status_entry
 267 structure.
 268 .Pp
 269 The
 270 .Fn mt_status_entry_free
 271 function frees the tree of status data underneath
 272 .Ar entry .
 273 .Pp
 274 The
 275 .Fn mt_status_free
 276 function frees the tree of status data underneath
 277 .Ar status_data .
 278 .Pp
 279 The
 280 .Fn mt_entry_sbuf
 281 function prints
 282 .Ar entry
 283 to the supplied sbuf
 284 .Ar sb ,
 285 optionally using the
 286 .Xr printf 3
 287 format
 288 .Ar fmt .
 289 If
 290 .Ar fmt
 291 is NULL, then
 292 .Fn mt_entry_sbuf
 293 will render integer types in base 10 without special formatting and all
 294 other types as they were rendered in the XML.
 295 .Pp
 296 .Fn mt_param_parent_sbuf
 297 prints the parents of the given
 298 .Ar entry
 299 to the supplied sbuf
 300 .Ar sb
 301 subject to the print parameters
 302 .Ar print_params .
 303 The result will be formatted with a period between each level, like
 304 "foo.bar.baz".
 305 .Pp
 306 .Fn mt_param_parent_print
 307 is like
 308 .Fn mt_param_parent_sbuf
 309 except that it prints the results to standard output instead of an sbuf.
 310 .Pp
 311 .Fn mt_param_entry_sbuf
 312 prints the
 313 .Ar entry
 314 to the given sbuf
 315 .Ar sb .
 316 The argument
 317 .Ar arg
 318 is a pointer to struct mt_print_params, which allows the caller to control
 319 the printing output.
 320 This function is intended to be supplied as an argument to
 321 .Fn mt_status_tree_sbuf .
 322 .Pp
 323 .Fn mt_param_entry_print
 324 is like
 325 .Fn mt_param_entry_sbuf
 326 except that it prints to standard output instead of an sbuf.
 327 It is intended to be used as an argument to
 328 .Fn mt_status_tree_print .
 329 .Pp
 330 .Fn mt_protect_print
 331 prints tape drive protection information from the supplied
 332 .Ar status_data
 333 beginning at the node name defined as the root node for protection data.
 334 If the
 335 .Ar verbose
 336 argument is non-zero, protection entry descriptions will be printed.
 337 If it is zero, protection entry descriptions will not be printed.
 338 .Pp
 339 .Fn mt_param_list
 340 prints tape driver parameters information from the supplied
 341 .Ar status_data .
 342 If the
 343 .Ar param_name
 344 is non-NULL, only the named parameter will be printed.
 345 If
 346 .Ar quiet
 347 is non-zero, parameter descriptions will be omitted in the output.
 348 .Pp
 349 .Fn mt_density_name
 350 Returns a text identifier for the supplied numeric
 351 .Ar density_num .
 352 The
 353 .Ar density_num
 354 should currently be a value between 0 and 255 inclusive, since that is the
 355 valid range for
 356 .Tn SCSI
 357 density code values.
 358 See below for notes on the return values.
 359 .Pp
 360 .Fn mt_density_bp
 361 Returns the bits per inch or bits per mm values for a given density entry
 362 specified by the
 363 .Ar density_num .
 364 If the
 365 .Ar bpi
 366 argument is non-zero, the bits per inch value is returned.
 367 Otherwise, the bits per mm value is returned.
 368 .Pp
 369 .Fn mt_density_num
 370 returns a numeric value for a text density description.
 371 It does a case-insensitive comparison of density names in the density table
 372 to the supplied density name.
 373 .Pp
 374 .Fn mt_get_xml_str
 375 gets the current XML status / parameter string from the sa(4) driver
 376 instance referenced by the open file descriptor
 377 .Ar mtfd .
 378 The
 379 .Xr mtio 4
 380 .Xr ioctl 2
 381 to be used is supplied as the
 382 .Ar cmd
 383 argument.
 384 Currently the
 385 .Fn mt_get_xml_str
 386 function will work with the
 387 .Dv MTIOCEXTGET
 388 and
 389 .Dv MTIOCPARAMGET
 390 ioctls.
 391 The supplied
 392 .Ar xml_str
 393 will be filled in with a pointer to the complete XML status string.
 394 Multiple calls to the given
 395 .Xr ioctl 2
 396 are made and more space is malloced until all of the XML string is fetched.
 397 The string returned in the
 398 .Ar xml_str
 399 argument should be freed when it is no longer in use.
 400 .Sh RETURN VALUES
 401 .Fn mt_entry_find
 402 returns the first matching entry, or NULL if it fails to find a match.
 403 .Pp
 404 .Fn mt_status_entry_find
 405 returns the first matching entry, or NULL if it fails to find a match.
 406 .Pp
 407 .Fn mt_protect_print
 408 Returns 0 for success, and non-zero for failure.
 409 .Fn mt_protect_print
 410 can only fail if it cannot find protection information in the supplied
 411 status data.
 412 .Pp
 413 .Fn mt_param_list
 414 Returns 0 for success and non-zero for failure.
 415 .Fn mt_param_list
 416 can only fail if it cannot find parameter information in the supplied
 417 status data.
 418 .Pp
 419 .Fn mt_density_name
 420 returns a text description of a numeric density.
 421 The special density value 0 is decoded as "default".
 422 The special density value 0x7f is decoded as "same".
 423 If the density is not known,
 424 .Fn mt_density_name
 425 will return "UNKNOWN".
 426 .Pp
 427 .Fn mt_density_bp
 428 returns the bits per inch value for the given density (if the
 429 .Ar bpi
 430 field is non-zero), the bits per mm value otherwise, or 0 if the supplied
 431 .Ar density_num
 432 is not in the density table or the table entry does not include bpi / bpmm
 433 values.
 434 .Pp
 435 .Fn mt_density_num
 436 returns a numeric density value between 0 and 255 for the supplied density
 437 name.
 438 It returns 0 if the density name is not recognized.
 439 .Pp
 440 .Fn mt_get_xml_str
 441 returns 0 for success, and -1 for failure.
 442 .Sh SEE ALSO
 443 .Xr mt 1 ,
 444 .Xr mtio 4 ,
 445 .Xr sa 4
 446 .Sh HISTORY
 447 The MT library first appeared in
 448 .Fx 10.1 .
 449 .Sh AUTHORS
 450 .An Ken Merry Aq ken@FreeBSD.org
 451 .Sh BUGS
 452 The library interface is not complete, and may change in the future.
 453 Application authors should not rely on the library interface to be
 454 consistent in the immediate future.