'\" t -*- coding: UTF-8 -*-
.\" Copyright (C) 2017-2021  Pali Rohár <pali.rohar@gmail.com>
.\"
.\" This program is free software; 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.
.\"
.\" This program 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 UDFLABEL 8 "udftools" "Commands"

.SH NAME
udflabel \(em show or change UDF filesystem label

.SH SYNOPSIS
.BI "udflabel [encoding\-options] [block\-options] [identifier\-options] \
" device " [" new\-label "]"

.SH DESCRIPTION
When \fBudflabel\fP is invoked without \fBidentifier\-options\fP and without
specifying \fInew\-label\fP then it shows current label of UDF filesystem on
\fIdevice\fP to standard output terminated by new line. Otherwise it updates
UDF filesystem (up to the revision 2.60) on \fIdevice\fP with new specified
identifiers from \fBidentifier\-options\fP. Specifying \fInew\-label\fP is
synonym for both \fB\-\-lvid\fP and \fB\-\-vid\fP, see section
\fBUDF LABEL AND UUID\fP.

.SH OPTIONS

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

.SS "BLOCK OPTIONS"
.TP
.BI \-b,\-\-blocksize= " block\-size "
Specify the size of blocks in bytes. Valid block size for a UDF filesystem is
a power of two in the range from \fI512\fP to \fI32768\fP and must match a
device logical (sector) size. If omitted, \fBudflabel\fP tries to autodetect
block size. First it tries logical (sector) size and then all valid block sizes.

.TP
.BI \-\-startblock= " start\-block "
Specify the block location where the UDF filesystem starts. It is used for
calculating the block location of the Volume Recognition Sequence (32 kB after
the start block) and the first Anchor Volume Descriptor Pointer (256 blocks
after the start block).

Normally start block is \fI0\fP, but for Multisession UDF optical discs it is
the block location where the last session of Multisession UDF disc starts.

If omitted, \fBudflabel\fP for optical disc tries to detect start block of the
last session from disc Table Of Contents. Otherwise value \fI0\fP is used.

For accessing some previous session of Multisession UDF optical disc, it is
required to specify correct block where that previous session starts. And also
to specify where that session ends via \fB\-\-lastblock\fP option.

For Multisession UDF disc images stored in file there is no way to detect where
the last session starts and therefore it is necessary to specify the correct
start block location manually from the original optical disc Table Of Contents.

(Option available since udflabel 2.3)

.TP
.BI \-\-lastblock= " last\-block "
Specify the block location where the UDF filesystem ends. It is used for
calculating the block location of second and third Anchor Volume Descriptor
Pointer (256 blocks prior the last block and the last block itself).

Normally last block is \fInumber of disk blocks minus one\fP, but for
Multisession UDF optical discs when reading different session than the last one
(specified by \fB\-\-startblock\fP) it is the block location where the specified
session ends.

If omitted, \fBudflabel\fP for optical disc tried to detect the last recorded
block with fallback to the last block of device or disk file image.

For accessing some previous session of Multisession UDF optical disc, it is
required to specify correct value for both \fB\-\-startblock\fP and
\fB\-\-lastblock\fP options.

(Option available since udflabel 2.3)

.TP
.BI \-\-vatblock= " vat\-block "
Specify the block location of the Virtual Allocation Table. Virtual Allocation
Table is present only on UDF disks with Virtual Partition Map and must be at the
last written/recorded disk block.

If omitted, \fBudflabel\fP for optical disc tries to detect the last recorded
block with fallback to the last block of block device or disk file image or
block specified by \fB\-\-lastblock\fP. In most cases, this fallback does not
have to work and for disk file images with Virtual Allocation Table it is
necessary to specify the correct location.

Virtual Allocation Table contains Logical Volume Identifier (UDF Label).

.TP
.B \-\-force
Force updating UDF disks without write support or write protected UDF disks. \
Some UDF disks may have set write protect flag. Some media, like CD-ROM, DVD-ROM
or BD-ROM are read-only. Other media, like CD-RW or DVD-RW, are write-once. UDF
is designed also for such media where updating Label or Identifiers is not
possible. But in some rare cases, it could make sense to try and overwrite the
existing Label or Identifiers also for UDF filesystem which has Access Type
either Read-Only or Recordable (Write-Once). This is possible only if underlying
media supports overwriting. E.g. UDF image of CD-ROM stored on hard disk or
Read-Only UDF image burned to DVD-RAM or BD-RE discs. Option \fB\-\-force\fP
ignores UDF Access Type and treats it as Overwritable. Also it ignores UDF
\fISoftWriteProtect\fP and \fIHardWriteProtected\fP flags.

.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 which UDF blocks would be
overwritten.

.SS "IDENTIFIER OPTIONS"
.TP
.BI \-u,\-\-uuid= " uuid "
Specify the UDF uuid. Must be exactly 16 hexadecimal lowercase digits and is
used for first 16 characters of \fB\-\-fullvsid\fP option. Special value
\fIrandom\fP generates new uuid from local time and a random number. See section
\fBUDF LABEL AND UUID\fP.

.TP
.BI \-\-lvid= " new\-logical\-volume\-identifier "
Specify the new Logical Volume Identifier.

.TP
.BI \-\-vid= " new\-volume\-identifier "
Specify the new Volume Identifier.

.TP
.BI \-\-vsid= " new\-volume\-set\-identifier "
Specify the new 17.\(en127. character of Volume Set Identifier. See section
\fBUDF LABEL AND UUID\fP.

.TP
.BI \-\-fsid= " new\-file\-set\-identifier "
Specify the new File Set Identifier.

.TP
.BI \-\-fullvsid= " new\-full\-volume\-set\-identifier "
Specify the new Volume Set identifier. Overwrite previous \fB\-\-uuid\fP and
\fB\-\-vsid\fP options. See section \fBUDF LABEL AND UUID\fP.

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

.TP
.BI \-\-organization= " new\-organization\-name "
Specify the new 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 udflabel 2.3)

.TP
.BI \-\-contact= " new\-contact\-information "
Specify the new 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 udflabel 2.3)

.TP
.BI \-\-appid= " new\-application\-identifier "
Specify the new Application Identifier which identifies application that created
medium or filesystem. It is stored in UDF Primary Volume Descriptor. This
identifier can be empty or must start with \fI*\fP and contain only 7bit ASCII
characters. (Option available since udflabel 2.3)

.TP
.BI \-\-impid= " new\-developer\-identifier "
Specify the new Developer Identifier for Implementation Identifier. It is unique
identification of the implementation which created medium or filesystem. It is
stored in UDF Primary Volume Descriptor. This identifier must start with \fI*\fP
and contain only 7bit ASCII characters. (Option available since udflabel 2.3)

.SS ENCODING OPTIONS
.TP
.B \-\-locale
Treat identifier string options as strings encoded according to current locale
settings (default). Must be specified as the first argument.

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

.SH "UDF LABEL AND UUID"
UDF specification does not say anything about a disk label but it describes that
UDF Logical Volume Identifier is an extremely important field for media
identification in a jukebox as that field is displayed to the user. And based on
this statement it is a common practice for the majority of UDF implementations
to use UDF Logical Volume Identifier as a UDF disk label.

UDF specification does not have a concept of disk UUID like other filesystems. \
But mandates that the first 16 characters of UDF Volume Set Identifier are
unique, a non-fixed and a non-trivial value. Plus first eight characters are
hexadecimal digits. Windows application \fBformat.exe\fP and Mac OS X
application \fBnewfs_udf\fP are known to violates this requirement and set only
the first 8 characters as unique (others are fixed). Since, there are still a
lot of UDF implementations which use in the first 16 characters only hexadecimal
digits and all compliant UDF implementations have hexadecimal digits in the
first 8 characters, the following algorithm for generating stable UUID was
informally chosen and now is used by udftools, util-linux, grub2 and other
projects:

.RS
0. If Volume Set Identifier has less then 8 characters then stop with empty UUID
.br
1. Take the first 16 bytes from UTF-8 encoded string of Volume Set Identifier
.br
2. If all bytes are hexadecimal digits then use their lowercase form as UUID
.br
3. If first 8 bytes are not all hexadecimal digits then convert those 8 bytes to
their hexadecimal representation (resulting in 16 bytes) and use as UUID
.br
4. Otherwise, compose UUID from two 8 byte parts:
.RS
1. part: Use the lowercase form of the first 8 bytes (which are hexadecimal
digits)
.br
2. part: Convert next 4 bytes (9.\(en12. pos.) to their hexadecimal
representation
.RE
.RE

Which means that this generated UUID has always 16 hexadecimal lowercase
digits. In most cases, this UUID matches case-insensitively the first 16
characters of UDF Volume Set Identifier and for all disks compliant to the UDF
specification the first 8 bytes of UUID matches case-insensitively the first 8
characters of UDF Volume Set Identifier. In that algorithm was chosen UTF-8
encoding because it is the only commonly used Unicode transformation to bytes
with fixed points in all hexadecimal digits.

.SH "EXIT STATUS"
\fBudflabel\fP returns 0 if successful, non-zero if there are problems like
block device does not contain UDF filesystem or updating failed.

.SH LIMITATIONS
\fBudflabel\fP is not able to set new Label, Logical Volume Identifier and File
Set Identifier for disks with Virtual Allocation Table (used by Write Once
media).

\fBudflabel\fP prior to version 2.3 was unable to handle Multisession UDF discs
correctly. It always accessed only the first session (the oldest one) and not
the last session (the most recent).

\fBudflabel\fP prior to version 2.2 was unable to print and process Unicode
strings with code points above U+FFFF correctly. 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).

\fBudflabel\fP prior to version 2.2 ignored UDF \fISoftWriteProtect\fP and
\fIHardWriteProtected\fP flags and overwritten such disks without any notice.

\fBudflabel\fP prior to version 2.2 was not able to set a new Label, Logical
Volume Identifier and File Set Identifier for disks with Metadata Partition
(used by UDF revisions higher then 2.01).

\fBudflabel\fP prior to version 2.1 was not able to read Label correctly if the
disk had Virtual Allocation Table stored outside of Information Control Block.

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

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

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