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>[,...]] [-fhnrvVw] <nbt-file> <mount-point> DESCRIPTION This tool is a FUSE-based file system implementation for accessing NBT for- matted data, which is used by Minecraft to store various data about the game. Running this tool mounts a file system from the file specified by <nbt-file>; both standalone NBT file (usually has .dat suffix) and Minecraft Region file (usually has .mcr or .mca suffix) are supported. OPTIONS -f Operate in foreground. Useful for debugging. -h --help Print a brief usage message. -n Ignored. -o <fs-option>[,...] Pass generic mount options, FUSE-specific options, and/or NBT-spe- cific 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 Cancel any ro option that may be specified earlier. region Specify that <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 listing only, existing nodes whose names don't contain colon can al- ways be accessed either with or without the type prefix. umask=<mask> Set file mode mask using an octal number for NBT nodes, de- fault 0. writefile=<path> Set an alternative path for writing NBT data; the original <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, should be visible in the region root directory; default hid- den. 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 meaningful only when direct read(2)ing of directories is supported by the operating system and the FUSE implementation. -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 The NBT specification defines several types for a tag, they are mapped to file types as follows: +-----------------------------------------------------+ | 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 a name to reference a node, as type- prefix:name. For example an int64 node named RandomSeed under a compound named Data, the following 2 paths will reference the same node: Data/int64:RandomSeed compound:Data/RandomSeed Turning on mount option typeprefix will make this type prefix be automati- cally prepended to node names, when listing a compound using readdir(3); this could be useful to preserve the type information when copying a com- pound node recursively (such as using tar(1)), so it is possible for the copied nodes to be restored into another NBT later. To avoid ambiguity, nodes can be listed and accessed only with the corre- sponding type prefix when their name contains any colon. Referencing Nodes Under List Nodes under a list are accessed using index numbers starting from 0. They will also have same type; a pseudo file .type is available under any list to indicate the node type the list contains. Accessing Individual Node Any node represented as a regular file can be read and written directly us- ing read(2) and write(2); it can also be truncate(2)d to empty, but a num- ber-typed ( int8 , int16 , int32 , int64 , float32 and float64 ) node will turn its value into 0 after that. Nodes with type int8array or string sup- port lseek(2) and unlimited truncate(2) operations. When reading from a string node, a line feed character (\n) is appended to the end automati- cally; similarly, when writing to a string node, the trailing line feed character is stripped if one exists. list and compound nodes can contain other nodes, they can be accessed ac- cording to above rules. int32array and int64array nodes are represented as directories, the array elements are accessed using an index number starting with 0, as regular files under the directory. Creating a new regular file with an appropriate index number under the directory extends the array; missing elements be- tween the old tail index and new index, if any, will appear automatically with value 0 as well. 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 directly (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 speci- fied 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), ac- cording to the file type they represent; usual file system restrictions on directories apply, meaning that nodes represented as directories can not be removed unless they are 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 requires the use of a type-prefixed name. Under List Like compound, nodes under a list may be removed by using either unlink(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 to the tail of a list only; it is currently not pos- sible to insert a node in the middle of a list. Newly created nodes have a type specified by the list, which is indicated by the .type pseudo file. The list entry type may also be changed by writing a type prefix name into .type, 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) ac- cording to the rules above, but please note that a newly created list will have an invalid entry type; no node can be created under such a 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 initialized, by writing a 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 compound 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 nodes are considered regular files by the file system, or both nodes are considered directories by the file system, and the node being overwritten is an empty compound or list, or an int32ar- ray or int64array. Moving into List The node being moved must have a type that matches the entry type of desti- nation list. The new name must be an index number. The index number must point to either the next available entry at tail of the list, or an existing node in the list; if the index is pointing to an existing node and the node isn't a non-empty compound or list, it will be overwritten. CAVEATS Data is committed to underlying <nbt-file> only upon unmounting; if any- thing goes wrong during this process, an error message will be sent to sys- log(3), then the file system will be unmounted without saving some or all data. When modifying a Minecraft Region file, it is currently not possible to ex- tend a modified chunk beyond the space available for the chunk in that Re- gion file; although this should rarely happen unless a considerable amount of additional data was copied into a chunk. If this happens, an error will be logged and the oversized chunk will not be saved. EXAMPLES The following examples took place in a Unix shell (e.g. 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 node 0 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(4), fuse(4), fuse(8), fusermount(8), mount(8), mkfs.nbt(8) Named Binary Tag specification by Mojang nbtfsutils 2026 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+15.1.quarterly>