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.  On error, \-1 is returned, and
  47 .I errno
  48 is set to indicate the error.
  49 .SH ERRORS
  50 Possible errors include (but are not limited to) the following:
  51 .TP
  52 .B EFAULT
  53 .I label
  54 references an inaccessible memory area.
  55 .TP
  56 .B EINVAL
  57 The specified label exceeds the maximum label length for the filesystem.
  58 .TP
  59 .B ENOTTY
  60 This can appear if the filesystem does not support online label manipulation.
  61 .TP
  62 .B EPERM
  63 The calling process does not have sufficient permissions to set the label.
  64 .SH VERSIONS
  65 These
  66 .BR ioctl (2)
  67 operations first appeared in Linux 4.18.
  68 They were previously known as
  69 .B BTRFS_IOC_GET_FSLABEL
  70 and
  71 .B BTRFS_IOC_SET_FSLABEL
  72 and were private to Btrfs.
  73 .SH CONFORMING TO
  74 This API is Linux-specific.
  75 .SH NOTES
  76 The maximum string length for this interface is
  77 .BR FSLABEL_MAX ,
  78 including the terminating null byte (\(aq\\0\(aq).
  79 Filesystems have differing maximum label lengths, which may or
  80 may not include the terminating null.  The string provided to
  81 .B FS_IOC_SETFSLABEL
  82 must always be null-terminated, and the string returned by
  83 .B FS_IOC_GETFSLABEL
  84 will always be null-terminated.
  85 .SH SEE ALSO
  86 .BR ioctl (2),
  87 .BR blkid (8)