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