path: root/doc/udflabel.8

'\" t -*- coding: UTF-8 -*-
.\" Copyright (C) 2017  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 \- 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 show current label of UDF filesystem on
\fIdevice\fP to standard output terminated by new line. Otherwise it update
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 \fI\-\-lvid\fP and \fI\-\-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
power of two in range from 512 to 32768 and must match a device logical (sector)
size. If omitted, \fBudflabel\fP tries to autodetect block size. It tries logical
(sector) size and then all valid block sizes.

.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. In
most cases this fallback does not have to work and for disk file images with
Virtual Allocation Table is necessary to specify correct location.

Virtual Allocation Table on disks with UDF revisions higher then 1.50 contains
Logical Volume Identifier (UDF Label).

.TP
.B \-\-force
Force updating UDF disks without write support. 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 overwrite existing
Label or Identifiers also for UDF filesystem which has Access Type either
Read-Only or Recordable (Write-Once). This is possible only if underlaying 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 \fI\-\-force\fP ignores UDF
Access Type and treat it as Overwritable.

.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
\fBrandom\fP generates new uuid from local time and 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.-127. 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.

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

.TP
.B \-\-u8
Treat identifier string options as strings encoded in 8-bit OSTA Compressed
Unicode format, 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, equivalent to UCS-2BE. 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 first argument.

.TP
.B \-\-utf8
Treat identifier string options as strings encoded in UTF-8. Must be specified
as first argument.

.SH "UDF LABEL AND UUID"
UDF specification does not say anything about a disk label but describe that UDF
Logical Volume Identifier is 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 majority of UDF implementations to use UDF Logical
Volume Identifier as a UDF disk label.

UDF specification does not have 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 format.exe and Mac OS X application newfs_udf are
known to violates this requirement and set only the first 8 characters as unique
(others are fixed). Because there are still 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 lowercase form of the first 8 bytes (which are hexadecimal digits)
.br
2. part: Convert next 4 bytes (9.-12. 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 Metadata Partition (used by UDF revisions higher
then 2.01) or Virtual Allocation Table (used by Write Once media). Also is not
able to read Label correctly if disk has 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)