---
name: "mt"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/mt/3"
---

# mt(3)

Magnetic Tape library

## NAME

**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** – Magnetic Tape library

## LIBRARY

library “libmt”

## SYNOPSIS

**#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 consists of a number of functions designed to aid in interacting with the [sa(4)](/sa/4.md) driver. The [sa(4)](/sa/4.md) 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.

The **mt\_start\_element**(), **mt\_end\_element**(), and **mt\_char\_handler**() functions are designed to work with the [libbsdxml(3)](/libbsdxml/3.md) library, which is an XML parsing library. The user data for the XML parser should be set with **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 **mt\_start\_element**() and **mt\_end\_element**() with **XML\_SetElementHandler**(). The character data handler should be set 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. 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.

**mt\_status\_tree\_sbuf**() takes the root node of a tree of [sa(4)](/sa/4.md) driver status information, and displays it in an [sbuf(9)](/sbuf/9.md). The *sb* argument is the destination sbuf. The *entry* argument is the root of the tree. The *indent* argument 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. The *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 *arg* argument is an argument for the *sbuf\_func* function.

The **mt\_status\_tree\_print**() function is the same as the **mt\_status\_tree\_sbuf**() function, except that the tree is printed to standard out instead of to a sbuf.

The **mt\_entry\_find**() function 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". In the case of a single level name, it will match any node beneath *entry* that matches *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".

The **mt\_status\_entry\_find**() is the same as **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.

The **mt\_status\_entry\_free**() function frees the tree of status data underneath *entry*.

The **mt\_status\_free**() function frees the tree of status data underneath *status\_data*.

The **mt\_entry\_sbuf**() function prints *entry* to the supplied sbuf *sb*, optionally using the [printf(3)](/printf/3.md) 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**() is like **mt\_param\_parent\_sbuf**() except that 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**() is like **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 **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 the *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*. The *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 the *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)](/sa/4.md) driver instance referenced by the open file descriptor *mtfd*. The [mtio(4)](/mtio/4.md) [ioctl(2)](/ioctl/2.md) to be used is supplied as the *cmd* argument. Currently the **mt\_get\_xml\_str**() function 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)](/ioctl/2.md) 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

[mt(1)](/mt/1.md), [mtio(4)](/mtio/4.md), [sa(4)](/sa/4.md)

## HISTORY

The MT library first appeared in FreeBSD 10.1.

## AUTHORS

Ken Merry ⟨*ken@FreeBSD.org*⟩

## 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.