2 .\" Copyright (c) 2013, 2015 Spectra Logic Corporation
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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.
30 .\" Authors: Ken Merry (Spectra Logic Corporation)
38 .Nm mt_start_element ,
41 .Nm mt_status_tree_sbuf ,
42 .Nm mt_status_tree_print ,
43 .Nm mt_status_entry_free ,
46 .Nm mt_param_parent_print ,
47 .Nm mt_param_entry_print ,
48 .Nm mt_protect_print ,
55 .Nd Magnetic Tape library
65 .Fa "const char *name"
66 .Fa "const char **attr"
71 .Fa "const char *name"
76 .Fa "const XML_Char *str"
80 .Fo mt_status_tree_sbuf
82 .Fa "struct mt_status_entry *entry"
84 .Fa "void (*sbuf_func)(struct sbuf *sb, struct mt_status_entry *entry, void *arg)"
88 .Fo mt_status_tree_print
89 .Fa "struct mt_status_entry *entry"
91 .Fa "void (*print_func)(struct mt_status_entry *entry, void *arg)"
94 .Ft "struct mt_status_entry *"
96 .Fa "struct mt_status_entry *entry"
99 .Ft "struct mt_status_entry *"
100 .Fo mt_status_entry_find
101 .Fa "struct mt_status_data *status_data"
105 .Fo mt_status_entry_free
106 .Fa "struct mt_status_entry *entry)"
110 .Fa "struct mt_status_data *status_data"
114 .Fa "struct sbuf *sb"
115 .Fa "struct mt_status_entry *entry"
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"
125 .Fo mt_param_parent_print
126 .Fa "struct mt_status_entry *entry"
127 .Fa "struct mt_print_params *print_params"
130 .Fo mt_param_entry_sbuf
131 .Fa "struct sbuf *sb"
132 .Fa "struct mt_status_entry *entry"
136 .Fo mt_param_entry_print
137 .Fa "struct mt_status_entry *entry"
142 .Fa "struct mt_status_data *status_data"
147 .Fa "struct mt_status_data *status_data"
148 .Fa "char *param_name"
153 .Fa "int density_num"
157 .Fa "int density_num"
162 .Fa "const char *density_name"
167 .Fa "struct mt_status_data *status_data"
170 The MT library consists of a number of functions designed to aid in
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.
181 .Fn mt_start_element ,
185 functions are designed to work with the
187 library, which is an XML parsing library.
188 The user data for the XML parser should be set with
191 mt_status_data with the entries list initialized.
192 The element handlers for the XML parser should be set to
197 .Fn XML_SetElementHandler .
198 The character data handler should be set to
201 .Fn XML_SetCharacterDataHandler
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.
210 .Fn mt_status_tree_sbuf
211 takes the root node of a tree of
213 driver status information, and displays it in an
217 argument is the destination sbuf.
220 argument is the root of the tree.
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.
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
234 argument is an argument for 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
247 function returns the first entry in the tree starting at
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
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".
262 .Fn mt_status_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
270 .Fn mt_status_entry_free
271 function frees the tree of status data underneath
276 function frees the tree of status data underneath
293 will render integer types in base 10 without special formatting and all
294 other types as they were rendered in the XML.
296 .Fn mt_param_parent_sbuf
297 prints the parents of the given
301 subject to the print parameters
303 The result will be formatted with a period between each level, like
306 .Fn mt_param_parent_print
308 .Fn mt_param_parent_sbuf
309 except that it prints the results to standard output instead of an sbuf.
311 .Fn mt_param_entry_sbuf
318 is a pointer to struct mt_print_params, which allows the caller to control
320 This function is intended to be supplied as an argument to
321 .Fn mt_status_tree_sbuf .
323 .Fn mt_param_entry_print
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 .
331 prints tape drive protection information from the supplied
333 beginning at the node name defined as the root node for protection data.
336 argument is non-zero, protection entry descriptions will be printed.
337 If it is zero, protection entry descriptions will not be printed.
340 prints tape driver parameters information from the supplied
344 is non-NULL, only the named parameter will be printed.
347 is non-zero, parameter descriptions will be omitted in the output.
350 Returns a text identifier for the supplied numeric
354 should currently be a value between 0 and 255 inclusive, since that is the
358 See below for notes on the return values.
361 Returns the bits per inch or bits per mm values for a given density entry
366 argument is non-zero, the bits per inch value is returned.
367 Otherwise, the bits per mm value is returned.
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.
375 gets the current XML status / parameter string from the sa(4) driver
376 instance referenced by the open file descriptor
381 to be used is supplied as the
386 function will work with the
393 will be filled in with a pointer to the complete XML status string.
394 Multiple calls to the given
396 are made and more space is malloced until all of the XML string is fetched.
397 The string returned in the
399 argument should be freed when it is no longer in use.
402 returns the first matching entry, or NULL if it fails to find a match.
404 .Fn mt_status_entry_find
405 returns the first matching entry, or NULL if it fails to find a match.
408 Returns 0 for success, and non-zero for failure.
410 can only fail if it cannot find protection information in the supplied
414 Returns 0 for success and non-zero for failure.
416 can only fail if it cannot find parameter information in the supplied
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,
425 will return "UNKNOWN".
428 returns the bits per inch value for the given density (if the
430 field is non-zero), the bits per mm value otherwise, or 0 if the supplied
432 is not in the density table or the table entry does not include bpi / bpmm
436 returns a numeric density value between 0 and 255 for the supplied density
438 It returns 0 if the density name is not recognized.
441 returns 0 for success, and -1 for failure.
447 The MT library first appeared in
450 .An Ken Merry Aq ken@FreeBSD.org
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.