Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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)

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>

home | help