diff options
Diffstat (limited to 'lib/libmt/mt.3')
| -rw-r--r-- | lib/libmt/mt.3 | 454 |
1 files changed, 454 insertions, 0 deletions
diff --git a/lib/libmt/mt.3 b/lib/libmt/mt.3 new file mode 100644 index 0000000..eaf0194 --- /dev/null +++ b/lib/libmt/mt.3 @@ -0,0 +1,454 @@ +.\" +.\" Copyright (c) 2013, 2015 Spectra Logic Corporation +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions, and the following disclaimer, +.\" without modification. +.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer +.\" substantially similar to the "NO WARRANTY" disclaimer below +.\" ("Disclaimer") and any redistribution must be conditioned upon +.\" including a substantially similar Disclaimer requirement for further +.\" binary redistribution. +.\" +.\" NO WARRANTY +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING +.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGES. +.\" +.\" Authors: Ken Merry (Spectra Logic Corporation) +.\" +.\" $FreeBSD$ +.\" +.Dd February 13, 2015 +.Dt MT 3 +.Os +.Sh NAME +.Nm mt_start_element , +.Nm mt_end_element , +.Nm mt_char_handler , +.Nm mt_status_tree_sbuf , +.Nm mt_status_tree_print , +.Nm mt_status_entry_free , +.Nm mt_status_free , +.Nm mt_entry_sbuf , +.Nm mt_param_parent_print , +.Nm mt_param_entry_print , +.Nm mt_protect_print , +.Nm mt_param_list , +.Nm mt_density_name , +.Nm mt_density_bp , +.Nm mt_density_num , +.Nm mt_get_xml_str , +.Nm mt_get_status +.Nd Magnetic Tape library +.Sh LIBRARY +.Lb libmt +.Sh SYNOPSIS +.In sys/sbuf.h +.In bsdxml.h +.In mtlib.h +.Ft void +.Fo mt_start_element +.Fa "void *user_data" +.Fa "const char *name" +.Fa "const char **attr" +.Fc +.Ft void +.Fo mt_end_element +.Fa "void *user_data" +.Fa "const char *name" +.Fc +.Ft void +.Fo mt_char_handler +.Fa "void *user_data" +.Fa "const XML_Char *str" +.Fa "int len" +.Fc +.Ft void +.Fo mt_status_tree_sbuf +.Fa "struct sbuf *sb" +.Fa "struct mt_status_entry *entry" +.Fa "int indent" +.Fa "void (*sbuf_func)(struct sbuf *sb, struct mt_status_entry *entry, void *arg)" +.Fa "void *arg" +.Fc +.Ft void +.Fo mt_status_tree_print +.Fa "struct mt_status_entry *entry" +.Fa "int indent" +.Fa "void (*print_func)(struct mt_status_entry *entry, void *arg)" +.Fa "void *arg" +.Fc +.Ft "struct mt_status_entry *" +.Fo mt_entry_find +.Fa "struct mt_status_entry *entry" +.Fa "char *name" +.Fc +.Ft "struct mt_status_entry *" +.Fo mt_status_entry_find +.Fa "struct mt_status_data *status_data" +.Fa "char *name" +.Fc +.Ft void +.Fo mt_status_entry_free +.Fa "struct mt_status_entry *entry)" +.Fc +.Ft void +.Fo mt_status_free +.Fa "struct mt_status_data *status_data" +.Fc +.Ft void +.Fo mt_entry_sbuf +.Fa "struct sbuf *sb" +.Fa "struct mt_status_entry *entry" +.Fa "char *fmt" +.Fc +.Ft void +.Fo mt_param_parent_sbuf +.Fa "struct sbuf *sb" +.Fa "struct mt_status_entry *entry" +.Fa "struct mt_print_params *print_params" +.Fc +.Ft void +.Fo mt_param_parent_print +.Fa "struct mt_status_entry *entry" +.Fa "struct mt_print_params *print_params" +.Fc +.Ft void +.Fo mt_param_entry_sbuf +.Fa "struct sbuf *sb" +.Fa "struct mt_status_entry *entry" +.Fa "void *arg" +.Fc +.Ft void +.Fo mt_param_entry_print +.Fa "struct mt_status_entry *entry" +.Fa "void *arg" +.Fc +.Ft int +.Fo mt_protect_print +.Fa "struct mt_status_data *status_data" +.Fa "int verbose" +.Fc +.Ft int +.Fo mt_param_list +.Fa "struct mt_status_data *status_data" +.Fa "char *param_name" +.Fa "int quiet" +.Fc +.Ft "const char *" +.Fo mt_density_name +.Fa "int density_num" +.Fc +.Ft int +.Fo mt_density_bp +.Fa "int density_num" +.Fa "int bpi" +.Fc +.Ft int +.Fo mt_density_num +.Fa "const char *density_name" +.Fc +.Ft int +.Fo mt_get_status +.Fa "char *xml_str" +.Fa "struct mt_status_data *status_data" +.Fc +.Sh DESCRIPTION +The MT library consists of a number of functions designed to aid in +interacting with the +.Xr sa 4 +driver. +The +.Xr sa 4 +driver returns some status data as XML-formatted strings, and +the primary purpose of this library is to make it easier for the +software developer to parse those strings and extract the status values. +.Pp +The +.Fn mt_start_element , +.Fn mt_end_element , +and +.Fn mt_char_handler +functions are designed to work with the +.Xr libbbsdxml 3 +library, which is an XML parsing library. +The user data for the XML parser should be set with +.Fn XML_SetUserData +to a zeroed struct +mt_status_data with the entries list initialized. +The element handlers for the XML parser should be set to +.Fn mt_start_element +and +.Fn mt_end_element +with +.Fn XML_SetElementHandler . +The character data handler should be set to +.Fn mt_char_handler +with the +.Fn XML_SetCharacterDataHandler +function. +The error member of the status_data structure will be set to 0 if parsing +is successful, and non-zero if parsing failed. +In the event of a failure, the error_str member will contain an error +message describing the failure. +These functions will build a tree of tape driver status data that can be +searched and printed using the other functions in this library. +.Pp +.Fn mt_status_tree_sbuf +takes the root node of a tree of +.Xr sa 4 +driver status information, and displays it in an +.Xr sbuf 9 . +The +.Ar sb +argument is the destination sbuf. +The +.Ar entry +argument is the root of the tree. +The +.Ar indent +argument is the number of characters to indent the output. +Each recursive call to +.Fn mt_status_tree_sbuf +will have the indent level incremented by 2. +The +.Ar sbuf_func +argument is for a user-supplied alternate printing function. +If it is non-NULL, it will be called instead of the default output printing +code. +The +.Ar arg +argument is an argument for the +.Ar sbuf_func +function. +.Pp +The +.Fn mt_status_tree_print +function is the same as the +.Fn mt_status_tree_sbuf +function, except that the tree is printed to standard out instead of to a +sbuf. +.Pp +The +.Fn mt_entry_find +function returns the first entry in the tree starting at +.Ar entry +that matches +.Ar name . +The supplied node name can be a single level name like "foo", or it can +specify mulitple node names that must be matched, for instance "foo.bar.baz". +In the case of a single level name, it will match any node beneath +.Ar entry +that matches +.Ar name . +In the case of a multi-level name like "foo.bar.baz", it will return the +first entry named "baz" whose immediate parent is "bar" and where the +parent of "bar" is named "foo". +.Pp +The +.Fn mt_status_entry_find +is the same as +.Fn mt_entry_find , +except that it operates on the top level mt_status_data and all +mt_status_entry nodes below it instead of just an mt_status_entry +structure. +.Pp +The +.Fn mt_status_entry_free +function frees the tree of status data underneath +.Ar entry . +.Pp +The +.Fn mt_status_free +function frees the tree of status data underneath +.Ar status_data . +.Pp +The +.Fn mt_entry_sbuf +function prints +.Ar entry +to the supplied sbuf +.Ar sb , +optionally using the +.Xr printf 3 +format +.Ar fmt . +If +.Ar fmt +is NULL, then +.Fn mt_entry_sbuf +will render integer types in base 10 without special formatting and all +other types as they were rendered in the XML. +.Pp +.Fn mt_param_parent_sbuf +prints the parents of the given +.Ar entry +to the supplied sbuf +.Ar sb +subject to the print parameters +.Ar print_params . +The result will be formatted with a period between each level, like +"foo.bar.baz". +.Pp +.Fn mt_param_parent_print +is like +.Fn mt_param_parent_sbuf +except that it prints the results to standard output instead of an sbuf. +.Pp +.Fn mt_param_entry_sbuf +prints the +.Ar entry +to the given sbuf +.Ar sb . +The argument +.Ar arg +is a pointer to struct mt_print_params, which allows the caller to control +the printing output. +This function is intended to be supplied as an argument to +.Fn mt_status_tree_sbuf . +.Pp +.Fn mt_param_entry_print +is like +.Fn mt_param_entry_sbuf +except that it prints to standard output instead of an sbuf. +It is intended to be used as an argument to +.Fn mt_status_tree_print . +.Pp +.Fn mt_protect_print +prints tape drive protection information from the supplied +.Ar status_data +beginning at the node name defined as the root node for protection data. +If the +.Ar verbose +argument is non-zero, protection entry descriptions will be printed. +If it is zero, protection entry descriptions will not be printed. +.Pp +.Fn mt_param_list +prints tape driver parameters information from the supplied +.Ar status_data . +If the +.Ar param_name +is non-NULL, only the named parameter will be printed. +If +.Ar quiet +is non-zero, parameter descriptions will be omitted in the output. +.Pp +.Fn mt_density_name +Returns a text identifier for the supplied numeric +.Ar density_num . +The +.Ar density_num +should currently be a value between 0 and 255 inclusive, since that is the +valid range for +.Tn SCSI +density code values. +See below for notes on the return values. +.Pp +.Fn mt_density_bp +Returns the bits per inch or bits per mm values for a given density entry +specified by the +.Ar density_num . +If the +.Ar bpi +argument is non-zero, the bits per inch value is returned. +Otherwise, the bits per mm value is returned. +.Pp +.Fn mt_density_num +returns a numeric value for a text density description. +It does a case-insensitive comparison of density names in the density table +to the supplied density name. +.Pp +.Fn mt_get_xml_str +gets the current XML status / parameter string from the sa(4) driver +instance referenced by the open file descriptor +.Ar mtfd . +The +.Xr mtio 4 +.Xr ioctl 2 +to be used is supplied as the +.Ar cmd +argument. +Currently the +.Fn mt_get_xml_str +function will work with the +.Dv MTIOCEXTGET +and +.Dv MTIOCPARAMGET +ioctls. +The supplied +.Ar xml_str +will be filled in with a pointer to the complete XML status string. +Multiple calls to the given +.Xr ioctl 2 +are made and more space is malloced until all of the XML string is fetched. +The string returned in the +.Ar xml_str +argument should be freed when it is no longer in use. +.Sh RETURN VALUES +.Fn mt_entry_find +returns the first matching entry, or NULL if it fails to find a match. +.Pp +.Fn mt_status_entry_find +returns the first matching entry, or NULL if it fails to find a match. +.Pp +.Fn mt_protect_print +Returns 0 for success, and non-zero for failure. +.Fn mt_protect_print +can only fail if it cannot find protection information in the supplied +status data. +.Pp +.Fn mt_param_list +Returns 0 for success and non-zero for failure. +.Fn mt_param_list +can only fail if it cannot find parameter information in the supplied +status data. +.Pp +.Fn mt_density_name +returns a text description of a numeric density. +The special density value 0 is decoded as "default". +The special density value 0x7f is decoded as "same". +If the density is not known, +.Fn mt_density_name +will return "UNKNOWN". +.Pp +.Fn mt_density_bp +returns the bits per inch value for the given density (if the +.Ar bpi +field is non-zero), the bits per mm value otherwise, or 0 if the supplied +.Ar density_num +is not in the density table or the table entry does not include bpi / bpmm +values. +.Pp +.Fn mt_density_num +returns a numeric density value between 0 and 255 for the supplied density +name. +It returns 0 if the density name is not recognized. +.Pp +.Fn mt_get_xml_str +returns 0 for success, and -1 for failure. +.Sh SEE ALSO +.Xr mt 1 , +.Xr mtio 4 , +.Xr sa 4 +.Sh HISTORY +The MT library first appeared in +.Fx 10.1 . +.Sh AUTHORS +.An Ken Merry Aq ken@FreeBSD.org +.Sh BUGS +The library interface is not complete, and may change in the future. +Application authors should not rely on the library interface to be +consistent in the immediate future. |
