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