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 2020-04-20 "Linux" "Linux Programmer's Manual"
  24 .SH NAME
  25 ioctl_fslabel \- get or set a filesystem label
  26 .SH SYNOPSIS
  27 .br
  28 .B #include <sys/ioctl.h>
  29 .br
  30 .B #include <linux/fs.h>
  31 .sp
  32 .BI "int ioctl(int " fd ", FS_IOC_GETFSLABEL, char " label [FSLABEL_MAX]);
  33 .br
  34 .BI "int ioctl(int " fd ", FS_IOC_SETFSLABEL, char " label [FSLABEL_MAX]);
  35 .SH DESCRIPTION
  36 If a filesystem supports online label manipulation, these
  37 .BR ioctl (2)
  38 operations can be used to get or set the filesystem label for the filesystem
  39 on which
  40 .B fd
  41 resides.
  42 The
  43 .B FS_IOC_SETFSLABEL
  44 operation requires privilege
  45 .RB ( CAP_SYS_ADMIN ).
  46 .SH RETURN VALUE
  47 On success zero is returned.  On error, \-1 is returned, and
  48 .I errno
  49 is set to indicate the error.
  50 .PP
  51 .SH ERRORS
  52 Error can include (but are not limited to) the following:
  53 .TP
  54 .B EFAULT
  55 .I label
  56 references an inaccessible memory area.
  57 .TP
  58 .B EINVAL
  59 The specified label exceeds the maximum label length for the filesystem.
  60 .TP
  61 .B ENOTTY
  62 This can appear if the filesystem does not support online label manipulation.
  63 .TP
  64 .B EPERM
  65 The calling process does not have sufficient permissions to set the label.
  66 .SH VERSIONS
  67 These
  68 .BR ioctl (2)
  69 operations first appeared in Linux 4.18.
  70 They were previously known as
  71 .B BTRFS_IOC_GET_FSLABEL
  72 and
  73 .B BTRFS_IOC_SET_FSLABEL
  74 and were private to Btrfs.
  75 .SH CONFORMING TO
  76 This API is Linux-specific.
  77 .SH NOTES
  78 The maximum string length for this interface is
  79 .BR FSLABEL_MAX ,
  80 including the terminating null byte (\(aq\\0\(aq).
  81 Filesystems have differing maximum label lengths, which may or
  82 may not include the terminating null.  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)