FreeBSD Manual Pages
MOUNT.NBT(8) System Manager's Manual MOUNT.NBT(8) NAME mount.nbt - Mount a Named Binary Tag File System SYNOPSIS mount.nbt [-o <fs-option>[,...]] [-fnrvwh] <nbt-file> <mount-point> DESCRIPTION This tool is a FUSE-based file system implementation for accessing NBT formatted data, which is used by Minecraft to store various data about the game. Running this tool mounts a file system from the file speci- fied by <nbt-file>; both standalone NBT file (usually have suffix .dat) and Minecraft Region file (usually have suffix .mcr or .mca) are sup- ported. OPTIONS -f Operate in foreground. Useful for debugging. -h --help Print a brief usage message. -n Ignored. -o <fs-option>[,...] Pass gereric mount options, FUSE-specific options, and/or NBT- specific options, in a comma-separated list. See mount(8) and fuse(8) for generic mount options and FUSE-specific options. NBT-specific options are: ro Mount the file system read-only, useful to mount from a file that can't be written to, or to prevent accidentally changing it; but see writefile option below. rw Revert any ro option that may be specified early. region Specify the <nbt-file> is a Minecraft Region file instead of a standalone NBT file. typeprefix Use node type prefix for node names when listing compound nodes as a directory. This option affects directory list- ing only, existing nodes where their name contains no colon can always be accessed either with or without the type prefix. umask=<mask> Set file mode mask using an octal number for NBT nodes, default 0. writefile=<path> Set an alternative path for writing NBT data; the origi- nal <nbt-file> won't be written to if this is specified. Will have no effect when file system is mounted read- only. compression={gzip|zlib} Set compression format for writing NBT data; default gzip for standalone NBT file, zlib for Minecraft Region file. Will have no effect when file system is mounted read- only. chunksymlink={hidden|visible} Set whether the symbolic links in form of <x>,<z> for chunks, be visible in the region root directory; default hidden. This option is meaningful only when mounting a Minecraft Region file. arraybyteorder={host|big|little} Set integer byte order for presenting data of int32array and int64array nodes; default host. This option is mean- ingful only when direct read(2)ing of directories is sup- ported by the operating system and the FUSE implementa- tion. -r Mount the file system read-only. Same as specifying -o ro. -v --verbose Be Verbose during mounting. -V --version Display version, copyright and licensing information of this tool. The program will exit afterward. -w Mount the file system read-write. Same as specifying -o rw. NODE TYPES NBT specification defined several types for a tag, they are mapped into file types as followings: +-----------------------------------------------------+ | NBT Tag Type File Type Type Prefix Name | | TAG_Byte Regular int8, byte | | TAG_Short Regular int16 | | TAG_Int Regular int32 | | TAG_Long Regular int64 | | TAG_Float Regular float32, float, single | | TAG_Double Regular float64, double | | TAG_Byte_Array Regular int8array, bytearray | | TAG_String Regular string | | TAG_List Directory list | | TAG_Compound Directory compound | | TAG_Int_Array Directory int32array | | TAG_Long_Array Directory int64array | +-----------------------------------------------------+ ACCESSING NODES Referencing Nodes Under Compound For nodes directly under a compound, they can be accessed using their name; a type prefix can also be prepended to an name to reference a node, as typeprefix:name. For example an int64 node named RandomSeed under a compound named Data, the following 2 paths would referencing the exactly same node: Data/int64:RandomSeed compound:Data/RandomSeed Turning on mount option typeprefix will having this type prefix be au- tomatically prepended to node names, when listing a compound using readdir(3); this could be useful to preserve the type information when copying a compound node recursively (such as using tar(1)), so it is possible for the copied nodes be restored into another NBT later. To avoid ambiguity, nodes can be listed and accessed only with the cor- responding type prefix when their name containing the colon. Referencing Nodes Under List Nodes under a list are accessed using index numbers starting with 0. They will also have same type; a pseudo file .type is available under any list to indicate node type the list contains. Accessing Individual Node Any node which the file type is regular file can be read and written directly using read(2) and write(2); they can also be truncate(2)d to empty, but number typed ( int8 , int16 , int32 , int64 , float32 and float64 ) nodes will turn its value into 0 after that. Nodes with type int8array or string support lseek(2) and unlimited truncate(2) opera- tions. Reading from a string node will have an additional line feed character (\n) appended to the end automatically; similarly, writing to a string node will have the ending line feed character stripped if ex- ist. list and compound nodes can contain other nodes, they can be accessed according to above rules. int32array and int64array nodes are represented as directories, the ar- ray elements are accessed using an index number starting with 0, as regular files under the directory. Creating a new regular file with appreciate index number under the directory extends the array, and any element between the old tail index and new index will appear automati- cally as well; automatically added elements are initialized to 0. An array can also be shrunk by removing (unlink(2)) the tail element, one element at a time; as a design limitation, only the tail element can be removed. On supported platforms, the array nodes may also be read di- rectly (using read(2)); in this case seeking is supported only when aligned to element size, which is 4 or 8 for int32array or int64array respectively. The data stream read directly from an array will be the binary representation of the array elements in a byte order specified by the mount option arraybyteorder, which is host byte order by de- fault. ADDING AND REMOVING NODES Under Compound Nodes under a compound can be removed by using unlink(2) or rmdir(2), according to their represented file type; usual file system restric- tions on directory apply, meaning nodes that being represented as di- rectories can not be removed unless empty. New node may be created under a compound by using either open(2) or mkdir(2). Unlike referencing an existing node, creating a new node re- quires the use of a type-prefixed name. Under List Like compound, nodes under a list may be removed by using either un- link(2) or rmdir(2); if a non-tail node was removed, the index number of later nodes will be shifted backward by 1, which could be surprising when trying to remove multiple nodes. New node may be added only to the tail of a list; there is currently not possible to insert a node in middle of a list. Newly created node will have the type specified by the list type, indicated by the .type pseudo file. The list type may also be changed by writing a type prefix name into .type, but only when the list is empty. Special Requirement For Creating List Node A list node may be created under either compound or list using mkdir(2) according to rules above, but please note newly created list will have an invalid list type; no node can be created under such list, and if a file system is unmounted with it, writing NBT data will fail, causing all modifications to be lost! Any newly created list must be initial- ized with a supported list type, by writing the type prefix name to its .type pseudo file. MOVING (RENAMING) NODES Any node can be moved from a compound or list, to same or another com- pound or list, by using rename(2). Moving into Compound If the new name is specified with a type prefix, the specified type prefix name must match the type of the node being moved. If another node in target compound with the new name already exists, it will be overwritten if: both node is considered as a regular file by the file system, or both node is considered as a directory by the file system, and the node being overwritten is an empty compound or list, or an int32array or int64array. Moving into List The node being moved must have a type that fit the list type. The new name must be an index number. The index number must be point to either the tail of the list, or an existing node in the list; if it is pointing to an existing node and the node isn't a non-empty compound or list, the node will be overwritten. CAVEATS Data is committed to underlying <nbt-file> only upon unmounting; if anything went wrong during this process, the error message will be sent to syslog(3), and the file system will be unmounted without saving some or all data. When modifying a Minecraft Region file, it is currently not possible to extend a modified chunk beyond the space available for the chunk in that Region file; although this rarely happen unless a considerable amount of additional data was copied into a chunk. If this happens, such chunk will not be saved. EXAMPLES The following examples took place in an Unix shell (sh(1)). Mount a standalone NBT file /tmp/level.dat at /mnt/nbt, prepare to write a new NBT file at /tmp/new-level.dat: mount.nbt -o writefile=/tmp/new-level.dat /tmp/level.dat /mnt/nbt Mount a Minecraft Region file /tmp/r.0.-1.mcr at /mnt/region, with type prefix turned on for node name listing: mount.nbt -o region,typeprefix /tmp/r.0.-1.mcr /mnt/region Working in a compound, create and write a new string node named id: echo Villager > string:id Working in a compound, create a new list node Pos with list type set to float64, then create and write first node in the list: mkdir list:Pos echo float64 > Pos/.type echo 31.5 > Pos/0 AUTHOR mount.nbt was written by WHR <whr@rivoreo.one>. SEE ALSO fusefs(5), fuse(8), fusermount(8), mount(8), mkfs.nbt(8) Named Binary Tag specification by Mojang nbtfsutils 2025 MOUNT.NBT(8)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | NODE TYPES | ACCESSING NODES | ADDING AND REMOVING NODES | MOVING (RENAMING) NODES | CAVEATS | EXAMPLES | AUTHOR | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=mount.nbt&sektion=8&manpath=FreeBSD+Ports+14.3.quarterly>