'\" t -*- coding: UTF-8 -*-
.\" Copyright 2002 Paul Thompson <set@pobox.com>
.\" Copyright 2014-2021 Pali Rohár <pali.rohar@gmail.com>
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License along
.\" with this program; if not, write to the Free Software Foundation, Inc.,
.\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
.\"
.TH MKUDFFS 8 "udftools" "System Management Commands"

.SH NAME
mkudffs \(em create a UDF filesystem

.SH SYNOPSIS
.BI "mkudffs [ options ] " device " [ " blocks\-count " ] "

.SH DESCRIPTION
\fBmkudffs\fP is used to create a UDF filesystem on a device (usually a disk). \
\fIdevice\fP is the special file corresponding to the device (e.g. \
\fI/dev/hdX\fP) or file image. \fIblocks\-count\fP is the number of blocks on
the device. If omitted, \fBmkudffs\fP automagically figures the filesystem
size. The order of options matters. Encoding option must be first and options to
override default settings implied by the media type or UDF revision should be
after the option they are overriding.

.SH OPTIONS
.TP
.B \-h,\-\-help
Display the usage and list of options.

.TP
.BI \-l,\-\-label= " label "
Specify the UDF label. UDF label is synonym for specifying both \fB\-\-lvid\fP
and \fB\-\-vid\fP options. If omitted, \fBmkudffs\fP label is \fILinuxUDF\fP. \
(Option available since mkudffs 1.1)

.TP
.BI \-u,\-\-uuid= " uuid "
Specify the UDF uuid. It must be exactly 16 hexadecimal lowercase digits and is
used for first 16 characters of \fB\-\-fullvsid\fP option. If omitted,
\fBmkudffs\fP uuid is generated from local time and a random number. (Option
available since mkudffs 1.1)

.TP
.BI \-b,\-\-blocksize= " block\-size "
Specify the size of blocks in bytes. Valid block size for a UDF filesystem is
power of two in range from \fI512\fP to \fI32768\fP and must match a device
logical (sector) size. If omitted, \fBmkudffs\fP block size is set to device
logical block (sector) size. If logical block (sector) size is unknown (e.g. \
when creating disk image) then for \fB\-\-media\-type\fP=\fIhd\fP is used block
size \fI512\fP and for other media types \fI2048\fP. (Prior to mkudffs 1.1
default value was always 2048 independently of \fB\-\-media\-type\fP)

.TP
.BI \-m,\-\-media\-type= " media\-type "
Specify the media type. Must be specified before \fB\-\-udfrev\fP. Default
value is autodetected. When autodetection does not work (e.g. when creating
disk image) then \fIhd\fP value is assumed. Valid media types are:
.RS 1.2i
.TP 1.6i
.I hd
HD (Hard Disk)
.TP
.I worm
WORM (Write Once Read Many)
.TP
.I mo
MO (Magneto Optical)
.TP
.I cd
CD-ROM (CD Read-Only Memory)
.TP
.I cdr
CD-R (CD Recordable)
.TP
.I cdrw
CD-RW (CD Read-Write)
.TP
.I dvd
DVD-ROM (DVD Read-Only Memory)
.TP
.I dvdr
DVD-R (DVD Recordable)
.TP
.I dvdrw
DVD-RW (DVD Read-Write)
.TP
.I dvdram
DVD-RAM (DVD Random Access Memory)
.TP
.I bdr
BD-R (Blu-ray Disc Recordable)
.RE

.RS
(Short option variant \fB\-m\fP and values \fIcd\fP, \fIdvdr\fP, \fIbdr\fP are
available since mkudffs 2.0 and autodetection is supported since mkudffs 2.2)
.RE

.TP
.BI \-r,\-\-udfrev= " udf\-revision "
Specify the UDF revision to use, either in hexadecimal BCD (e.g. \fI0x0201\fP)
or decimal (e.g. \fI2.01\fP) format. Valid revisions are \fI1.01\fP, \fI1.02\fP,
\fI1.50\fP, \fI2.00\fP, \fI2.01\fP, \fI2.50\fP and \fI2.60\fP. If omitted,
\fBmkudffs\fP UDF revision is \fI2.01\fP, except for Blu-ray Discs which is
\fI2.50\fP. UDF revisions higher then \fI2.01\fP are experimental. Option must
be specified after \fB\-\-media\-type\fP. (Values in decimal format and UDF
revisions higher then \fI2.01\fP are supported since mkudffs 2.0, UDF revision
1.01 is supported since mkudffs 2.1)

.TP
.B \-n,\-\-no\-write
Not really, do not write to \fIdevice\fP. Just simulate and display what would
happen with \fIdevice\fP. Useful for determining the calculated location of
different UDF blocks. (Option available since mkudffs 2.0)

.TP
.B \-\-new\-file
Create a new image file specified by \fIdevice\fP with \fIblocks\-count\fP and
fail if file already exists. If omitted, \fBmkudffs\fP creates a new image file
only in case it does not exist yet. (Option available since mkudffs 2.0)

.TP
.BI \-\-lvid= " logical\-volume\-identifier "
Specify the \fILogical Volume Identifier\fP. If omitted, \fBmkudffs\fP Logical
Volume Identifier is \fILinuxUDF\fP. Most UDF implementations use this
identifier as a disk label.

.TP
.BI \-\-vid= " volume\-identifier "
Specify the \fIVolume Identifier\fP. If omitted, \fBmkudffs\fP Volume Identifier
is \fILinuxUDF\fP.

.TP
.BI \-\-vsid= " volume\-set\-identifier "
Specify the 17.\(en127. character of \fIVolume Set Identifier\fP. If omitted,
\fBmkudffs\fP Volume Set Identifier is \fILinuxUDF\fP.

.TP
.BI \-\-fsid= " file\-set\-identifier "
Specify the \fIFile Set Identifier\fP. If omitted, \fBmkudffs\fP File Set
Identifier is \fILinuxUDF\fP.

.TP
.BI \-\-fullvsid= " full\-volume\-set\-identifier "
Specify the full \fIVolume Set Identifier\fP. Overwrite previous \fB\-\-uuid\fP
and \fB\-\-vsid\fP options. (Option available since mkudffs 1.1)

.TP
.BI \-\-owner= " owner\-name "
Specify the Owner name, person creating the medium or filesystem. It is stored
in UDF Logical Volume Info1, part of UDF Implementation Use Volume Descriptor. \
(Option available since mkudffs 2.3)

.TP
.BI \-\-organization= " organization\-name "
Specify the Organization name responsible for creating the medium or
filesystem. It is stored in UDF Logical Volume Info2, part of UDF Implementation
Use Volume Descriptor. (Option available since mkudffs 2.3)

.TP
.BI \-\-contact= " contact\-information "
Specify the Contact information for the medium or filesystem. It is stored
in UDF Logical Volume Info3, part of UDF Implementation Use Volume Descriptor. \
(Option available since mkudffs 2.3)

.TP
.BI \-\-uid= " uid "
Specify the uid of the root (/) directory. If omitted, \fBmkudffs\fP uid is
\fI0\fP. Special value \fI\-1\fP means invalid or not specified uid. (Option
available since mkudffs 1.1)

.TP
.BI \-\-gid= " gid "
Specify the gid of the root (/) directory. If omitted, \fBmkudffs\fP gid is
\fI0\fP. Special value \fI\-1\fP means invalid or not specified gid. (Option
available since mkudffs 1.1)

.TP
.BI \-\-mode= " mode "
Specify permissions in octal mode bits of the root (/) directory. If omitted,
\fBmkudffs\fP mode is \fI0755\fP. (Option available since mkudffs 2.0)

.TP
.BI \-\-read\-only
This option specify that the whole UDF disk should be treated as read-only. It
sets \fISoftWriteProtect\fP domain flag in \fILogical Volume Descriptor\fP and
in \fIFile Set Descriptor\fP. Plus for overwritable media types (\fIhd\fP,
\fIdvdram\fP, \fIdvdrw\fP) set \fIUDF Access Type\fP to read-only. (Option
available since mkudffs 2.2)

.TP
.BI \-\-bootarea= " fill "
Specify how to fill UDF boot area which is the first 32kB of the disk and is not
used by UDF itself. Option \fImbr\fP make sense only when running \fBmkudffs\fP
on whole disk, not on just one partition. Valid options are:
.RS 1.2i
.TP 1.4i
.I preserve
preserve existing UDF boot area, do not touch it (default for media type
different from \fIhd\fP)
.TP
.I erase
erase existing UDF boot area, fill it by zeros (default for \fIhd\fP media type
on partitions and on removable disks)
.TP
.I mbr
put MBR table with one partition which starts at sector 0 (includes MBR itself)
and spans whole disk device, needed only for non-removable hard disks used on
Microsoft Windows systems (default for \fIhd\fP media type on non-removable hard
disk without partitions), see section \fBWHOLE DISK VS PARTITION\fP
.TP
.IB mbr: "sec-size"
same as \fImbr\fP but explicitly set MBR sector size to \fIsec-size\fP value,
default \fIsec-size\fP is device logical block (sector) size with fallback to
size \fI512\fP bytes
.RE

.RS
(Option available since mkudffs 2.0)
.RE

.TP
.BI \-\-strategy= " strategy "
Specify the allocation strategy to use. Valid strategies are \fI4\fP and
\fI4096\fP. If omitted, \fBmkudffs\fP strategy is based on the
\fB\-\-media\-type\fP.

.TP
.BI \-\-spartable,\ \-\-spartable= " spartable\-number "
Enable usage Sparing Table. Optionally specify also the number of sparing
tables. Valid numbers are \fI1\(en4\fP. When the spartable number is omitted
then two tables are written to the disc. If the option is omitted then usage of
Sparing Table depends on the media type. (Option prior to mkudffs 2.0 was
available only for \fIcdrw\fP media type)

.TP
.BI \-\-sparspace= " num\-of\-entires "
Specify the number of entries in Sparing Table. If omitted, the default number
of entries is \fI1024\fP, but depends on the media type. (Option available since
mkudffs 2.0)

.TP
.BI \-\-packetlen= " length "
Packet length in a number of blocks used for alignment. All continuous UDF
structures would be aligned to packets. It specifies also the size of the
Sparing Space and packet length in Sparing Table. It should match the device
ECC/packet length. If omitted, default value for DVD discs is \fI16\fP blocks,
for CD/BD discs it is \fI32\fP blocks and otherwise \fI1\fP block. (Option prior
to mkudffs 2.1 was available only for \fIcdrw\fP and \fIdvdrw\fP media types)

.TP
.B \-\-vat
Enable usage of Virtual Allocation Table (VAT). If omitted, usage depends on
the media type. (Option available since mkudffs 2.0)

.TP
.BI \-\-startblock= " start\-block "
Specify the block location where the UDF filesystem starts.

Normally start block is \fI0\fP, but when creating second or higher session for
Multisession UDF optical disc it is the block location where that new session
starts.

When updating existing Multisession UDF image file, \fBmkudffs\fP overwrites
only data blocks for a new session at start block position in the image file.

When creating a new UDF image file, \fBmkudffs\fP stores only data blocks for a
new session at beginning of the image file. Therefore data for start block would
be written to the zero block instead of the start block. Such image without
leading blocks (where are located previous sessions) is suitable for burning a
new session to the optical disc. But it cannot be read or detected by any UDF
tool until leading zero blocks (or previous sessions) are prepended to the image
file.

For calculating position where a new session of particular optical disc should
start is required to use software which would be used for burning newly created
image. So for example, if for burning is used \fBwodim\fP(1) then second value
on output from \fB\%wodim\% \-msinfo\fP call is start block. Accordingly for
\fBcdrecord\fP(1) call \fB\%cdrecord\% \-msinfo\fP or for \fBcdrdao\fP(1) call
\fB\%cdrdao\% msinfo\fP or for \fBxorriso\fP(1) call
\fB\%xorriso\% \-as\% cdrecord\% dev=/dev/cdrw\% \-msinfo\fP.

(Option available since mkudffs 2.3)

.TP
.BI \-\-minblocks= " min\-num\-of\-blocks "
Specify minimal number of blocks to write on disc with Virtual Allocation Table.

This option affects block position where is written Virtual Allocation Table.
And in case option \fB\-\-closed\fP is used then also it affects block position
of the second Anchor Volume Descriptor Pointer.

Default value for \fIcdr\fP media type is 300. This is safe default to allow
burning CD-R disc image in Track-at-Once mode. This mode requires to burn image
with minimal size of 300 sectors. Burning CD-R discs in other modes (e.g. \
Disc-at-Once or Packet-Writing) may allow to allow to use also smaller disc
images.

For all other media types there is no default minimal limit.

(Option available since mkudffs 2.3)

.TP
.B \-\-closed
Close disc with Virtual Allocation Table. AVDP is written also to the end of
the disc. By default, the disc with Virtual Allocation Table is not closed.

.TP
.BI \-\-space= " space "
Specify the Space Set. \fIUnallocated\fP Space Set is used for media which
blocks may be allocated immediately. \fIFreed\fP Space Set is used for media
which blocks needs to be specially prepared/erased before allocation. In Space
\fITable\fP is stored list of unallocated extents. In Space \fIBitmap\fP is
stored bitmap of unallocated blocks. Not used for VAT.
.RS 1.2i
.TP 1.6i
.I freedbitmap
Freed Bitmap
.TP
.I freedtable
Freed Table
.TP
.I unallocbitmap
Unallocated Bitmap (default)
.TP
.I unalloctable
Unallocated Table
.RE

.TP
.BI \-\-ad= " ad "
Specify the Allocation Descriptors of the root (/) directory.
.RS 1.2i
.TP 1.6i
.I inicb
Allocation Descriptors in ICB (default)
.TP
.I short
Short Allocation Descriptors
.TP
.I long
Long Allocation Descriptors
.RE

.TP
.B \-\-noefe
Don't Use Extended File Entries for the root (/) directory. Affects only UDF
2.00 or higher. Must be specified after \fB\-\-udfrev\fP.

.TP
.B \-\-locale
Treat identifier string options as strings encoded according to the current
locale settings (default). Must be specified as the first argument. (Option
available since mkudffs 2.0)

.TP
.B \-\-u8
Treat identifier string options as strings encoded in 8-bit OSTA Compressed
Unicode format without leading Compression ID byte, which is equivalent to
Latin1 (ISO-8859-1). Must be specified as first argument.

.TP
.B \-\-u16
Treat identifier string options as strings encoded in 16-bit OSTA Compressed
Unicode format without leading Compression ID byte, which is equivalent to
UTF-16BE. Note that it is not possible to include zero byte in command line
options, therefore any character which has at least one zero byte cannot be
supplied (this applies to all Latin1 characters). Must be specified as the
first argument.

.TP
.B \-\-utf8
Treat identifier string options as strings encoded in UTF-8. Must be specified
as the first argument. (Prior to mkudffs 2.0 this was default option)

.SH COMPATIBILITY

.SS "OPERATING SYSTEMS SUPPORT"
UDF filesystem is natively supported by large amount of operating systems. See
following compatibility table:

.TS
box;
c s|c s
c|c|c|c
l|l|c|c.
Operating system	Maximum UDF revision for
_
Name	Version	read	write
=
Linux	2.3.17 \(en 2.4.5	2.00	2.00
\^	2.4.6 \(en 2.6.25	2.01	2.01
\^	2.6.26 (and new)	2.50	2.01
_
Windows	98/Me	1.02	none
\^	2000	1.50	none
\^	XP	2.01	none
\^	Vista (and new)	2.60	2.50
_
Mac OS	8.1 \(en 8.5	1.02	none
\^	8.6 \(en 9.2	1.50	1.50
_
Mac OS X	10.0 \(en 10.3	1.50	1.50
\^	10.4	2.01	2.01
\^	10.5 (and new)	2.60	2.50
_
FreeBSD	5 (and new)	1.50	none
_
NetBSD	4.0	2.60	none
\^	5.0 (and new)	2.60	2.60
_
OpenBSD	3.8 \(en 3.9	1.02	none
\^	4.0 \(en 4.6	1.50	\^
\^	4.7 (and new)	2.60	\^
_
Solaris	7 (and new)	1.50	1.50
_
AIX	5.2 (and new)	2.01	2.01
.TE

Note that Windows 98 and Windows Me can read UDF filesystem only from CD and DVD
optical discs, not from hard disks.

.SS "BLOCK SIZE"
In most cases, operating systems are unable to mount UDF filesystem if UDF block
size differs from logical sector size of the device. Typically hard disks have
sector size 512 bytes and optical media 2048 bytes. Therefore UDF block size
must match the logical sector size of the device.

Linux kernel prior to version 2.6.30 used hardcoded UDF block size of 2048 bytes
independently of logical sector size, therefore it was not able to automatically
mount UDF filesystem if block size differed from 2048. Since 2.6.30 and prior to
4.11 Linux kernel used a logical sector size of the device as UDF block size,
plus it tried fallback to 2048. Since 4.11 it uses logical sector size and
fallbacks to any valid block size between logical sector size and 4096. \
Therefore since version 2.6.30 Linux kernel can automatically mount UDF
filesystems correctly if UDF block size matches device logical sector size and
since version 4.11 can automatically also mount devices which sector size does
not match UDF block size. In any case and also for Linux kernel prior to version
2.6.30, different UDF block size (which is not autodetected) can be manually
specified via \fBbs\fP=\fIblocksize\fP mount parameter.

.SS "WHOLE DISK VS PARTITION"
UDF filesystem is supposed to be formatted on the whole media and not to the
partitioned hard disk. Mac OS X systems enforce this rule and reject to
automatically mount UDF filesystem unless it is formatted on the whole
unpartitioned hard disk. Possible partition table (e.g. MBR or GPT) on disk with
valid UDF filesystem is ignored. On the other hand, Microsoft Windows systems
are unable to detect non-removable hard disks without MBR or GPT partition
table. Removable disks do not have this restriction. A consequence is that
non-removable hard disks formatted to UDF by Windows Vista+ are not recognized
by Mac OS X systems and vice-versa. Note that manual mount of UDF partition on
partitioned hard disk on Mac OS X system is possible and working (e.g. by
running commands: \f(CW\%mkdir \%/Volumes/DriveName \%&& \%mount_udf
\%/dev/disk1s1 \%/Volumes/DriveName\fP). But there is no known way to mount an
unpartitioned non-removable disk on Windows system.

Thanks to reserved and unused UDF boot area (first 32kB of UDF filesystem) it is
possible to deal with this problem, by putting MBR on such non-removable hard
disk just for compatibility reasons with Windows. Such MBR table would contain
one partition which starts at sector 0 (includes MBR itself) and spans whole
disk device. So the whole disk device and also the first partition on disk
points to same sectors. Therefore UDF filesystem can be mounted either from
whole disk device (needed for Mac OS X systems) or from first partition (needed
for Microsoft Windows systems).

Linux kernel ignores MBR table if contains partition which starts at sector 0. \
Normally Linux kernel can detect and mount UDF filesystem either on a partition
or on whole disk device. It does not have any restrictions.

\fBmkudffs\fP option \fB\-\-bootarea\fP=\fImbr\fP put such MBR table for
compatibility with Microsoft Windows systems into disk when formatting.

.SS "LINUX LABEL BUGS"
In most cases \fILogical Volume Identifier\fP is used as UDF label. But Linux
libblkid prior to version 2.26 used \fIVolume Identifier\fP. Therefore
\fBmkudffs\fP \fB\-\-label\fP for compatibility reasons set both \fILogical
Volume Identifier\fP and \fIVolume Identifier\fP.

Linux libblkid prior to version 2.30 incorrectly processed non-ASCII identifier
strings encoded in 8-bit OSTA Compressed Unicode format. Therefore \fBmkudffs\fP
since version 2.0 for compatibility reasons tries to encode a non-ASCII
identifier strings in 16-bit OSTA Compressed Unicode format and then fallbacks
to 8-bit format.

For more information about UDF Label and UUID see \fBudflabel\fP(8) section
\fBUDF LABEL AND UUID\fP.

.SH "EXIT STATUS"
\fBmkudffs\fP returns 0 if successful, non-zero if there are problems.

.SH LIMITATIONS
\fBmkudffs\fP cannot create UDF 2.50 Metadata partition, therefore it does not
support UDF revisions higher than 2.01 for non Write Once media yet. So there is
no support for Blu-ray discs which needs UDF 2.50 (except for Blu-ray Disc
Recordable which does not require Metadata partition).

\fBmkudffs\fP prior to version 2.2 was unable to process Unicode strings with
code points above U+FFFF. When option \fB\-\-utf8\fP was specified then input
strings were limited to 3-byte UTF-8 sequences and when option \fB\-\-u16\fP
was specified then input strings were limited just to UCS-2BE strings (subset
of UTF-16BE).

.SH BUGS
\fBmkudffs\fP prior to version 1.1 was unable to process non-ASCII characters
from identifier strings in \fB\-\-utf8\fP mode, \fB\-\-vsid\fP option was
completely broken and \fB\-\-blocksize\fP must have been manually specified for
hard disks as default value was hardcoded for optical disks. \fBmkudffs\fP prior
to version 2.0 generated broken and unreadable \fIcdr\fP disc images.

.SH AUTHOR
.nf
Ben Fennema
Pali Rohár <pali.rohar@gmail.com>
.fi

.SH AVAILABILITY
\fBmkudffs\fP is part of the udftools package and is available from
https://github.com/pali/udftools/.

.SH SEE ALSO
\fBpktsetup\fP(8), \fBudflabel\fP(8), \fBcdrwtool\fP(1), \fBudfinfo\fP(1),
\fBwrudf\fP(1)