man2/ioctl_fslabel.2

   1 .\" Copyright (c) 2018, Red Hat, Inc.  All rights reserved.
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\"
   9 .\" The GNU General Public License's references to "object code"
  10 .\" and "executables" are to be interpreted as the output of any
  11 .\" document formatting or typesetting system, including
  12 .\" intermediate and printed output.
  13 .\"
  14 .\" This manual is distributed in the hope that it will be useful,
  15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 .\" GNU General Public License for more details.
  18 .\"
  19 .\" You should have received a copy of the GNU General Public
  20 .\" License along with this manual; if not, see
  21 .\" <http://www.gnu.org/licenses/>.
  22 .\" %%%LICENSE_END
  23 .TH IOCTL_FSLABEL 2 2021-03-22 "Linux" "Linux Programmer's Manual"
  24 .SH NAME
  25 ioctl_fslabel \- get or set a filesystem label
  26 .SH SYNOPSIS
  27 .nf
  28 .BR "#include <linux/fs.h>" "       /* Definition of " *FSLABEL* " constants */"
  29 .B #include <sys/ioctl.h>
  30 .PP
  31 .BI "int ioctl(int " fd ", FS_IOC_GETFSLABEL, char " label [FSLABEL_MAX]);
  32 .BI "int ioctl(int " fd ", FS_IOC_SETFSLABEL, char " label [FSLABEL_MAX]);
  33 .fi
  34 .SH DESCRIPTION
  35 If a filesystem supports online label manipulation, these
  36 .BR ioctl (2)
  37 operations can be used to get or set the filesystem label for the filesystem
  38 on which
  39 .I fd
  40 resides.
  41 The
  42 .B FS_IOC_SETFSLABEL
  43 operation requires privilege
  44 .RB ( CAP_SYS_ADMIN ).
  45 .SH RETURN VALUE
  46 On success zero is returned.
  47 On error, \-1 is returned, and
  48 .I errno
  49 is set to indicate the error.
  50 .SH ERRORS
  51 Possible errors include (but are not limited to) the following:
  52 .TP
  53 .B EFAULT
  54 .I label
  55 references an inaccessible memory area.
  56 .TP
  57 .B EINVAL
  58 The specified label exceeds the maximum label length for the filesystem.
  59 .TP
  60 .B ENOTTY
  61 This can appear if the filesystem does not support online label manipulation.
  62 .TP
  63 .B EPERM
  64 The calling process does not have sufficient permissions to set the label.
  65 .SH VERSIONS
  66 These
  67 .BR ioctl (2)
  68 operations first appeared in Linux 4.18.
  69 They were previously known as
  70 .B BTRFS_IOC_GET_FSLABEL
  71 and
  72 .B BTRFS_IOC_SET_FSLABEL
  73 and were private to Btrfs.
  74 .SH CONFORMING TO
  75 This API is Linux-specific.
  76 .SH NOTES
  77 The maximum string length for this interface is
  78 .BR FSLABEL_MAX ,
  79 including the terminating null byte (\(aq\\0\(aq).
  80 Filesystems have differing maximum label lengths, which may or
  81 may not include the terminating null.
  82 The string provided to
  83 .B FS_IOC_SETFSLABEL
  84 must always be null-terminated, and the string returned by
  85 .B FS_IOC_GETFSLABEL
  86 will always be null-terminated.
  87 .SH SEE ALSO
  88 .BR ioctl (2),
  89 .BR blkid (8)