MT(3)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

💖 MT(3) — Magnetic Tape library 💖

okay bestie, this is the MT(3) page from the Library Functions Manual, and it's literally all about the Magnetic Tape library. no cap, it's giving “make XML tape status data make sense” energy. 🦋

🎀 NAME 🎀

the whole cast, in order, is:

mt_start_element
mt_end_element
mt_char_handler
mt_status_tree_sbuf
mt_status_tree_print
mt_status_entry_free
mt_status_free
mt_entry_sbuf
mt_param_parent_print
mt_param_entry_print
mt_protect_print
mt_param_list
mt_density_name
mt_density_bp
mt_density_num
mt_get_xml_str
mt_get_status

and yes, the whole thing is the Magnetic Tape library. periodt. 👑

🌸 LIBRARY 🌸

the library is literally “libmt”. that's the one, bestie. 💅

✨ SYNOPSIS ✨

here's the exact code tea — copy it character for character:

#include <sys/sbuf.h>
#include <bsdxml.h>
#include <mtlib.h>

void
mt_start_element(void *user_data, const char *name, const char **attr);

void
mt_end_element(void *user_data, const char *name);

void
mt_char_handler(void *user_data, const XML_Char *str, int len);

void
mt_status_tree_sbuf(struct sbuf *sb, struct mt_status_entry *entry,
    int indent,
    void (*sbuf_func)(struct sbuf *sb, struct mt_status_entry *entry, void *arg),
    void *arg);

void
mt_status_tree_print(struct mt_status_entry *entry, int indent,
    void (*print_func)(struct mt_status_entry *entry, void *arg),
    void *arg);

struct mt_status_entry *
mt_entry_find(struct mt_status_entry *entry, char *name);

struct mt_status_entry *
mt_status_entry_find(struct mt_status_data *status_data, char *name);

void
mt_status_entry_free(struct mt_status_entry *entry));

void
mt_status_free(struct mt_status_data *status_data);

void
mt_entry_sbuf(struct sbuf *sb, struct mt_status_entry *entry,
    char *fmt);

void
mt_param_parent_sbuf(struct sbuf *sb, struct mt_status_entry *entry,
    struct mt_print_params *print_params);

void
mt_param_parent_print(struct mt_status_entry *entry,
    struct mt_print_params *print_params);

void
mt_param_entry_sbuf(struct sbuf *sb, struct mt_status_entry *entry,
    void *arg);

void
mt_param_entry_print(struct mt_status_entry *entry, void *arg);

int
mt_protect_print(struct mt_status_data *status_data, int verbose);

int
mt_param_list(struct mt_status_data *status_data, char *param_name,
    int quiet);

const char *
mt_density_name(int density_num);

int
mt_density_bp(int density_num, int bpi);

int
mt_density_num(const char *density_name);

int
mt_get_status(char *xml_str, struct mt_status_data *status_data);

🦋 DESCRIPTION 🦋

the MT library is a bunch of functions made to help you vibe with the sa(4) driver. the 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. ✨

mt_start_element(), mt_end_element(), and mt_char_handler() are designed to work with the libbsdxml(3) library, which is an XML parsing library. set the user data for the XML parser with XML_SetUserData() to a zeroed struct mt_status_data with the entries list initialized. set the element handlers for the XML parser to mt_start_element() and mt_end_element() with XML_SetElementHandler(). set the character data handler to mt_char_handler() with the 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. if it fails, 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. 🎀

mt_status_tree_sbuf() — takes the root node of a tree of sa(4) driver status information, and displays it in an sbuf(9). sb is the destination sbuf, entry is the root of the tree, and indent is the number of characters to indent the output. each recursive call to mt_status_tree_sbuf() will have the indent level incremented by 2. sbuf_func is for a user-supplied alternate printing function; if it is non-NULL, it will be called instead of the default output printing code. arg is an argument for the sbuf_func function. 💅
mt_status_tree_print() — same as mt_status_tree_sbuf(), except the tree is printed to standard out instead of to a sbuf. ✨
mt_entry_find() — returns the first entry in the tree starting at entry that matches name. the supplied node name can be a single level name like "foo", or it can specify multiple node names that must be matched, for instance "foo.bar.baz". with a single level name, it will match any node beneath entry that matches name. with 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". 🔥
mt_status_entry_find() — same as mt_entry_find(), except 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. 🦋
mt_status_entry_free() — frees the tree of status data underneath entry. 🎀
mt_status_free() — frees the tree of status data underneath status_data. 🎀
mt_entry_sbuf() — prints entry to the supplied sbuf sb, optionally using the printf(3) format fmt. if fmt is NULL, then mt_entry_sbuf() will render integer types in base 10 without special formatting and all other types as they were rendered in the XML. 💖
mt_param_parent_sbuf() — prints the parents of the given entry to the supplied sbuf sb subject to the print parameters print_params. the result will be formatted with a period between each level, like "foo.bar.baz". 🌈
mt_param_parent_print() — like mt_param_parent_sbuf() except it prints the results to standard output instead of an sbuf. 🫶
mt_param_entry_sbuf() — prints the entry to the given sbuf sb. the argument 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 mt_status_tree_sbuf(). 🌸
mt_param_entry_print() — like mt_param_entry_sbuf() except it prints to standard output instead of an sbuf. it is intended to be used as an argument to mt_status_tree_print(). 🧚
mt_protect_print() — prints tape drive protection information from the supplied status_data beginning at the node name defined as the root node for protection data. if the verbose argument is non-zero, protection entry descriptions will be printed. if it is zero, protection entry descriptions will not be printed. 👑
mt_param_list() — prints tape driver parameters information from the supplied status_data. if param_name is non-NULL, only the named parameter will be printed. if quiet is non-zero, parameter descriptions will be omitted in the output. 💜
mt_density_name() — returns a text identifier for the supplied numeric density_num. density_num should currently be a value between 0 and 255 inclusive, since that is the valid range for SCSI density code values. see below for notes on the return values. ⭐
mt_density_bp() — returns the bits per inch or bits per mm values for a given density entry specified by density_num. if the bpi argument is non-zero, the bits per inch value is returned. otherwise, the bits per mm value is returned. 🍓
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. 🦋
mt_get_xml_str() — gets the current XML status / parameter string from the sa(4) driver instance referenced by the open file descriptor mtfd. the mtio(4) ioctl(2) to be used is supplied as the cmd argument. currently mt_get_xml_str() will work with the MTIOCEXTGET and MTIOCPARAMGET ioctls. the supplied xml_str will be filled in with a pointer to the complete XML status string. multiple calls to the given ioctl(2) are made and more space is malloced until all of the XML string is fetched. the string returned in the xml_str argument should be freed when it is no longer in use. 💀

🔥 RETURN VALUES 🔥

mt_entry_find() — returns the first matching entry, or NULL if it fails to find a match. 😭
mt_status_entry_find() — returns the first matching entry, or NULL if it fails to find a match. 😭
mt_protect_print() — returns 0 for success, and non-zero for failure. mt_protect_print() can only fail if it cannot find protection information in the supplied status data. 🫶
mt_param_list() — returns 0 for success and non-zero for failure. mt_param_list() can only fail if it cannot find parameter information in the supplied status data. 🫶
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, mt_density_name() will return "UNKNOWN". ⭐
mt_density_bp() — returns the bits per inch value for the given density (if the bpi field is non-zero), the bits per mm value otherwise, or 0 if the supplied density_num is not in the density table or the table entry does not include bpi / bpmm values. 🍓
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. 💜
mt_get_xml_str() — returns 0 for success, and -1 for failure. 💀

🌈 SEE ALSO 🌈

go check out mt(1), mtio(4), and sa(4). bestie homework, but make it cute. 📚

⭐ HISTORY ⭐

the MT library first appeared in FreeBSD 10.1. iconic. 👑

👑 AUTHORS 👑

Ken Merry <ken@FreeBSD.org> 🫶

💀 BUGS 💀

okay so real talk: 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. 😭

💖 that's the tea! this page is from Debian, dated February 13, 2015. 🎀

📦 where this page comes from

freebsd 14.5: base 14.5
freebsd 15.1: base 15.1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms