DCMD_FSYS_LABEL, DCMD_FSYS_LABEL

Get the filesystem label

Synopsis:

#include <sys/dcmd_blk.h>

#define DCMD_FSYS_LABEL       __DIOF(_DCMD_FSYS,  22, char[256])
#define DCMD_FSYS_LABEL_RAW   __DIOF(_DCMD_FSYS,  27, uint8_t[256])

Arguments to devctl():

Argument	Value
`filedes`	A file descriptor that you obtained by opening the device.
`dcmd`	DCMD_FSYS_LABEL or DCMD_FSYS_LABEL_RAW
`dev_data_ptr`	A char[256] or uint8_t[256] buffer
`n_bytes`	The size of the buffer
`dev_info_ptr`	NULL

Description:

The DCMD_FSYS_LABEL command gets the filesystem's volume label as a string in UTF-8 Unicode format; DCMD_FSYS_LABEL_RAW gets the label as an array of unsigned characters with no conversions performed.

A number of filesystems store the volume label on the media in formats other than UTF-8 Unicode. For example, the Windows NT filesystem stores the volume label in UTF-16 Unicode format; our NTFS implementation (fs-nt.so) converts it to UTF-8 Unicode.

The DOS filesystem stores volume labels in a variety of formats:

Old versions of DOS can use SBCS (Single-Byte Character Set) or DBCS (Double-Byte Character Set) encoding, also known as DOS codepages.
Windows may use UTF-16 Unicode.
Linux may use UTF-8 Unicode.

Our DOS filesystem (fs-dos.so) tries to convert the label to UTF-8 Unicode, but it can't automatically determine which encoding was used; you can use the dos codepage=... option to specify the encoding. If the DOS filesystem fails to convert any characters in the label to UTF-8 Unicode, it replaces them with the “bad” ASCII character. By default, this is the ASCII underscore (_) character (ASCII code 0x5F), but you can change this with the dos badchar=... option.

You can use the DCMD_FSYS_LABEL_RAW command to work around the difficulties with character conversions that DCMD_FSYS_LABEL may run into. DCMD_FSYS_LABEL_RAW gets the bytes as they're stored on the media, without any conversion. You can then convert the string to whatever character set you wish.

Input:

None.

Output:

The filesystem label.

Example:

#include <stdio.h>
#include <stdlib.h>
#include <devctl.h>
#include <sys/dcmd_blk.h>
#include <errno.h>
#include <string.h>
#include <fcntl.h>

int main (void)
{
    int fd;
    int ret;
    char vol_label[256];

    fd = open ("/dev/hd0t179", O_RDONLY);
    if (fd == -1)
    {
        perror ("open()");
        return (EXIT_FAILURE);
    }

    memset (vol_label, 0, sizeof(vol_label));
    ret = devctl(fd, DCMD_FSYS_LABEL, vol_label, sizeof(vol_label), NULL);

    if (ret == EOK)
    {
        printf ("Label: %s\n", vol_label);
    } else {
        printf ("DCMD_FSYS_LABEL failed: %s\n", strerror(ret) );
        return (EXIT_FAILURE);
    }

    return (EXIT_SUCCESS);
}