| .\" Copyright (c) 2018, Red Hat, Inc. All rights reserved. |
| .\" |
| .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
| .\" This is free documentation; 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. |
| .\" |
| .\" The GNU General Public License's references to "object code" |
| .\" and "executables" are to be interpreted as the output of any |
| .\" document formatting or typesetting system, including |
| .\" intermediate and printed output. |
| .\" |
| .\" This manual 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 manual; if not, see |
| .\" <http://www.gnu.org/licenses/>. |
| .\" %%%LICENSE_END |
| .TH IOCTL_FSLABEL 2 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| ioctl_fslabel \- get or set a filesystem label |
| .SH SYNOPSIS |
| .nf |
| .BR "#include <linux/fs.h>" " /* Definition of " *FSLABEL* " constants */" |
| .B #include <sys/ioctl.h> |
| .PP |
| .BI "int ioctl(int " fd ", FS_IOC_GETFSLABEL, char " label [FSLABEL_MAX]); |
| .BI "int ioctl(int " fd ", FS_IOC_SETFSLABEL, char " label [FSLABEL_MAX]); |
| .fi |
| .SH DESCRIPTION |
| If a filesystem supports online label manipulation, these |
| .BR ioctl (2) |
| operations can be used to get or set the filesystem label for the filesystem |
| on which |
| .I fd |
| resides. |
| The |
| .B FS_IOC_SETFSLABEL |
| operation requires privilege |
| .RB ( CAP_SYS_ADMIN ). |
| .SH RETURN VALUE |
| On success zero is returned. On error, \-1 is returned, and |
| .I errno |
| is set to indicate the error. |
| .SH ERRORS |
| Possible errors include (but are not limited to) the following: |
| .TP |
| .B EFAULT |
| .I label |
| references an inaccessible memory area. |
| .TP |
| .B EINVAL |
| The specified label exceeds the maximum label length for the filesystem. |
| .TP |
| .B ENOTTY |
| This can appear if the filesystem does not support online label manipulation. |
| .TP |
| .B EPERM |
| The calling process does not have sufficient permissions to set the label. |
| .SH VERSIONS |
| These |
| .BR ioctl (2) |
| operations first appeared in Linux 4.18. |
| They were previously known as |
| .B BTRFS_IOC_GET_FSLABEL |
| and |
| .B BTRFS_IOC_SET_FSLABEL |
| and were private to Btrfs. |
| .SH CONFORMING TO |
| This API is Linux-specific. |
| .SH NOTES |
| The maximum string length for this interface is |
| .BR FSLABEL_MAX , |
| including the terminating null byte (\(aq\\0\(aq). |
| Filesystems have differing maximum label lengths, which may or |
| may not include the terminating null. The string provided to |
| .B FS_IOC_SETFSLABEL |
| must always be null-terminated, and the string returned by |
| .B FS_IOC_GETFSLABEL |
| will always be null-terminated. |
| .SH SEE ALSO |
| .BR ioctl (2), |
| .BR blkid (8) |