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)
39 .Nm mt_start_element ,
42 .Nm mt_status_tree_sbuf ,
43 .Nm mt_status_tree_print ,
44 .Nm mt_status_entry_free ,
47 .Nm mt_param_parent_print ,
48 .Nm mt_param_entry_print ,
49 .Nm mt_protect_print ,
56 .Nd Magnetic Tape library
66 .Fa "const char *name"
67 .Fa "const char **attr"
72 .Fa "const char *name"
77 .Fa "const XML_Char *str"
81 .Fo mt_status_tree_sbuf
83 .Fa "struct mt_status_entry *entry"
85 .Fa "void (*sbuf_func)(struct sbuf *sb, struct mt_status_entry *entry, void *arg)"
89 .Fo mt_status_tree_print
90 .Fa "struct mt_status_entry *entry"
92 .Fa "void (*print_func)(struct mt_status_entry *entry, void *arg)"
95 .Ft "struct mt_status_entry *"
97 .Fa "struct mt_status_entry *entry"
100 .Ft "struct mt_status_entry *"
101 .Fo mt_status_entry_find
102 .Fa "struct mt_status_data *status_data"
106 .Fo mt_status_entry_free
107 .Fa "struct mt_status_entry *entry)"
111 .Fa "struct mt_status_data *status_data"
115 .Fa "struct sbuf *sb"
116 .Fa "struct mt_status_entry *entry"
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"
126 .Fo mt_param_parent_print
127 .Fa "struct mt_status_entry *entry"
128 .Fa "struct mt_print_params *print_params"
131 .Fo mt_param_entry_sbuf
132 .Fa "struct sbuf *sb"
133 .Fa "struct mt_status_entry *entry"
137 .Fo mt_param_entry_print
138 .Fa "struct mt_status_entry *entry"
143 .Fa "struct mt_status_data *status_data"
148 .Fa "struct mt_status_data *status_data"
149 .Fa "char *param_name"
154 .Fa "int density_num"
158 .Fa "int density_num"
163 .Fa "const char *density_name"
168 .Fa "struct mt_status_data *status_data"
171 The MT library consists of a number of functions designed to aid in
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.
182 .Fn mt_start_element ,
186 functions are designed to work with the
188 library, which is an XML parsing library.
189 The user data for the XML parser should be set with
192 mt_status_data with the entries list initialized.
193 The element handlers for the XML parser should be set to
198 .Fn XML_SetElementHandler .
199 The character data handler should be set to
202 .Fn XML_SetCharacterDataHandler
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.
211 .Fn mt_status_tree_sbuf
212 takes the root node of a tree of
214 driver status information, and displays it in an
218 argument is the destination sbuf.
221 argument is the root of the tree.
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.
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
235 argument is an argument for 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
248 function returns the first entry in the tree starting at
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
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".
263 .Fn mt_status_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
271 .Fn mt_status_entry_free
272 function frees the tree of status data underneath
277 function frees the tree of status data underneath
294 will render integer types in base 10 without special formatting and all
295 other types as they were rendered in the XML.
297 .Fn mt_param_parent_sbuf
298 prints the parents of the given
302 subject to the print parameters
304 The result will be formatted with a period between each level, like
307 .Fn mt_param_parent_print
309 .Fn mt_param_parent_sbuf
310 except that it prints the results to standard output instead of an sbuf.
312 .Fn mt_param_entry_sbuf
319 is a pointer to struct mt_print_params, which allows the caller to control
321 This function is intended to be supplied as an argument to
322 .Fn mt_status_tree_sbuf .
324 .Fn mt_param_entry_print
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 .
332 prints tape drive protection information from the supplied
334 beginning at the node name defined as the root node for protection data.
337 argument is non-zero, protection entry descriptions will be printed.
338 If it is zero, protection entry descriptions will not be printed.
341 prints tape driver parameters information from the supplied
345 is non-NULL, only the named parameter will be printed.
348 is non-zero, parameter descriptions will be omitted in the output.
351 Returns a text identifier for the supplied numeric
355 should currently be a value between 0 and 255 inclusive, since that is the
359 See below for notes on the return values.
362 Returns the bits per inch or bits per mm values for a given density entry
367 argument is non-zero, the bits per inch value is returned.
368 Otherwise, the bits per mm value is returned.
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.
376 gets the current XML status / parameter string from the sa(4) driver
377 instance referenced by the open file descriptor
382 to be used is supplied as the
387 function will work with the
394 will be filled in with a pointer to the complete XML status string.
395 Multiple calls to the given
397 are made and more space is malloced until all of the XML string is fetched.
398 The string returned in the
400 argument should be freed when it is no longer in use.
403 returns the first matching entry, or NULL if it fails to find a match.
405 .Fn mt_status_entry_find
406 returns the first matching entry, or NULL if it fails to find a match.
409 Returns 0 for success, and non-zero for failure.
411 can only fail if it cannot find protection information in the supplied
415 Returns 0 for success and non-zero for failure.
417 can only fail if it cannot find parameter information in the supplied
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,
426 will return "UNKNOWN".
429 returns the bits per inch value for the given density (if the
431 field is non-zero), the bits per mm value otherwise, or 0 if the supplied
433 is not in the density table or the table entry does not include bpi / bpmm
437 returns a numeric density value between 0 and 255 for the supplied density
439 It returns 0 if the density name is not recognized.
442 returns 0 for success, and -1 for failure.
448 The MT library first appeared in
451 .An Ken Merry Aq ken@FreeBSD.org
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.