2015-04-22 06:28:34 +00:00
|
|
|
.\" Extended attributes manual page
|
|
|
|
.\"
|
|
|
|
.\" Copyright (C) 2000, 2002, 2007 Andreas Gruenbacher <agruen@suse.de>
|
|
|
|
.\" Copyright (C) 2001, 2002, 2004, 2007 Silicon Graphics, Inc.
|
|
|
|
.\" All rights reserved.
|
|
|
|
.\"
|
2015-05-07 06:10:31 +00:00
|
|
|
.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
|
2015-04-22 06:28:34 +00:00
|
|
|
.\" 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/>.
|
2015-05-07 06:10:31 +00:00
|
|
|
.\" %%%LICENSE_END
|
2015-04-22 06:28:34 +00:00
|
|
|
.\"
|
iconv.1, locale.1, memusage.1, memusagestat.1, pldd.1, sprof.1, _syscall.2, add_key.2, adjtimex.2, bind.2, bpf.2, chown.2, clone.2, close.2, copy_file_range.2, eventfd.2, fanotify_init.2, fanotify_mark.2, fork.2, fsync.2, futex.2, getdents.2, getrlimit.2, getxattr.2, io_cancel.2, io_destroy.2, io_getevents.2, io_setup.2, ioctl_fat.2, ioctl_getfsmap.2, ioctl_ns.2, ioctl_tty.2, ioctl_userfaultfd.2, kcmp.2, keyctl.2, listen.2, listxattr.2, mbind.2, membarrier.2, memfd_create.2, mkdir.2, move_pages.2, mremap.2, msync.2, nfsservctl.2, open.2, perf_event_open.2, pidfd_send_signal.2, pipe.2, pivot_root.2, pkey_alloc.2, process_vm_readv.2, ptrace.2, readlink.2, readv.2, recv.2, recvmmsg.2, rename.2, request_key.2, s390_runtime_instr.2, sched_setaffinity.2, seccomp.2, send.2, sendmmsg.2, sigaltstack.2, signalfd.2, socket.2, socketpair.2, splice.2, spu_create.2, spu_run.2, statfs.2, syscall.2, sysctl.2, sysfs.2, tee.2, timer_getoverrun.2, timer_settime.2, umount.2, userfaultfd.2, utimensat.2, wait4.2, INFINITY.3, __ppc_get_timebase.3, __setfpucw.3, abort.3, aio_cancel.3, aio_error.3, aio_read.3, aio_return.3, atexit.3, backtrace.3, basename.3, bsearch.3, bswap.3, cacos.3, cacosh.3, catan.3, catanh.3, cexp2.3, clock_getcpuclockid.3, clog2.3, cmsg.3, confstr.3, div.3, dl_iterate_phdr.3, dlerror.3, dlinfo.3, dlopen.3, dlsym.3, duplocale.3, encrypt.3, end.3, endian.3, envz_add.3, err.3, expm1.3, fdim.3, flockfile.3, fmtmsg.3, frexp.3, ftw.3, get_nprocs_conf.3, get_phys_pages.3, getaddrinfo_a.3, getauxval.3, getdate.3, getdtablesize.3, getgrent_r.3, getgrouplist.3, gethostbyname.3, getline.3, getnameinfo.3, getopt.3, getprotoent_r.3, getpwent_r.3, getpwnam.3, getservent_r.3, getsubopt.3, getutent.3, glob.3, gnu_get_libc_version.3, hsearch.3, if_nameindex.3, inet.3, inet_net_pton.3, inet_ntop.3, inet_pton.3, insque.3, killpg.3, makecontext.3, mallinfo.3, malloc.3, malloc_hook.3, malloc_info.3, mallopt.3, matherr.3, mbsnrtowcs.3, mbstowcs.3, mcheck.3, mempcpy.3, mq_getattr.3, mq_notify.3, mtrace.3, newlocale.3, nextafter.3, ntp_gettime.3, offsetof.3, open_memstream.3, pow.3, printf.3, pthread_attr_init.3, pthread_attr_setdetachstate.3, pthread_attr_setguardsize.3, pthread_attr_setinheritsched.3, pthread_attr_setschedparam.3, pthread_attr_setschedpolicy.3, pthread_attr_setstack.3, pthread_attr_setstacksize.3, pthread_cancel.3, pthread_cleanup_push.3, pthread_create.3, pthread_detach.3, pthread_getattr_default_np.3, pthread_getattr_np.3, pthread_getcpuclockid.3, pthread_join.3, pthread_mutex_consistent.3, pthread_mutexattr_setrobust.3, pthread_setaffinity_np.3, pthread_setcancelstate.3, pthread_setname_np.3, pthread_setschedparam.3, pthread_sigmask.3, pthread_spin_init.3, pthread_testcancel.3, pthread_tryjoin_np.3, ptsname.3, qsort.3, rand.3, random.3, remainder.3, rpmatch.3, rtime.3, rtnetlink.3, scalb.3, scalbln.3, scandir.3, sem_getvalue.3, sem_wait.3, setaliasent.3, setlogmask.3, sigwait.3, sincos.3, sockatmark.3, stdarg.3, stpcpy.3, strcat.3, strfmon.3, strptime.3, strtod.3, strtok.3, strtol.3, strtoul.3, strverscmp.3, tsearch.3, uselocale.3, wcstok.3, wcstombs.3, wordexp.3, y0.3, loop.4, vcs.4, veth.4, charmap.5, core.5, filesystems.5, gai.conf.5, hosts.5, hosts.equiv.5, locale.5, nss.5, repertoiremap.5, securetty.5, shells.5, ttytype.5, ascii.7, complex.7, cpuset.7, credentials.7, fanotify.7, hier.7, inotify.7, ip.7, mount_namespaces.7, mq_overview.7, netlink.7, network_namespaces.7, pid_namespaces.7, pkeys.7, rtld-audit.7, rtnetlink.7, sem_overview.7, signal-safety.7, sock_diag.7, spufs.7, standards.7, symlink.7, tcp.7, time_namespaces.7, unix.7, user_namespaces.7, xattr.7, ldconfig.8: tstamp
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-06-09 12:43:54 +00:00
|
|
|
.TH XATTR 7 2020-06-09 "Linux" "Linux Programmer's Manual"
|
2015-04-22 06:28:34 +00:00
|
|
|
.SH NAME
|
2016-08-07 16:47:06 +00:00
|
|
|
xattr \- Extended attributes
|
2015-04-22 06:28:34 +00:00
|
|
|
.SH DESCRIPTION
|
|
|
|
Extended attributes are name:value pairs associated permanently with
|
|
|
|
files and directories, similar to the environment strings associated
|
|
|
|
with a process.
|
|
|
|
An attribute may be defined or undefined.
|
|
|
|
If it is defined, its value may be empty or non-empty.
|
|
|
|
.PP
|
|
|
|
Extended attributes are extensions to the normal attributes which are
|
2015-04-22 06:57:02 +00:00
|
|
|
associated with all inodes in the system (i.e., the
|
2015-04-22 06:28:34 +00:00
|
|
|
.BR stat (2)
|
|
|
|
data).
|
|
|
|
They are often used to provide additional functionality
|
2015-04-22 06:59:38 +00:00
|
|
|
to a filesystem\(emfor example, additional security features such as
|
2015-04-22 06:28:34 +00:00
|
|
|
Access Control Lists (ACLs) may be implemented using extended attributes.
|
|
|
|
.PP
|
2015-04-22 12:46:30 +00:00
|
|
|
Users with search access to a file or directory may use
|
|
|
|
.BR listxattr (2)
|
|
|
|
to retrieve a list of attribute names defined for that file or directory.
|
2015-04-22 06:28:34 +00:00
|
|
|
.PP
|
|
|
|
Extended attributes are accessed as atomic objects.
|
2015-04-22 12:46:30 +00:00
|
|
|
Reading
|
|
|
|
.RB ( getxattr (2))
|
|
|
|
retrieves the whole value of an attribute and stores it in a buffer.
|
|
|
|
Writing
|
|
|
|
.RB ( setxattr (2))
|
|
|
|
replaces any previous value with the new value.
|
2015-04-22 06:28:34 +00:00
|
|
|
.PP
|
2015-04-22 11:44:16 +00:00
|
|
|
Space consumed for extended attributes may be counted towards the disk quotas
|
2015-04-22 06:28:34 +00:00
|
|
|
of the file owner and file group.
|
2015-04-22 06:54:38 +00:00
|
|
|
.SS Extended attribute namespaces
|
2015-04-22 07:22:44 +00:00
|
|
|
Attribute names are null-terminated strings.
|
2015-04-22 06:28:34 +00:00
|
|
|
The attribute name is always specified in the fully qualified
|
|
|
|
.IR namespace.attribute
|
2015-04-22 06:57:02 +00:00
|
|
|
form, for example,
|
2015-04-22 06:28:34 +00:00
|
|
|
.IR user.mime_type ,
|
|
|
|
.IR trusted.md5sum ,
|
|
|
|
.IR system.posix_acl_access ,
|
|
|
|
or
|
|
|
|
.IR security.selinux .
|
|
|
|
.PP
|
|
|
|
The namespace mechanism is used to define different classes of extended
|
|
|
|
attributes.
|
2015-04-22 06:57:02 +00:00
|
|
|
These different classes exist for several reasons;
|
|
|
|
for example, the permissions
|
2015-04-22 06:28:34 +00:00
|
|
|
and capabilities required for manipulating extended attributes of one
|
|
|
|
namespace may differ to another.
|
|
|
|
.PP
|
2015-04-22 06:59:38 +00:00
|
|
|
Currently, the
|
2015-04-22 06:28:34 +00:00
|
|
|
.IR security ,
|
|
|
|
.IR system ,
|
|
|
|
.IR trusted ,
|
|
|
|
and
|
|
|
|
.IR user
|
2015-04-22 06:50:55 +00:00
|
|
|
extended attribute classes are defined as described below.
|
|
|
|
Additional classes may be added in the future.
|
2015-04-22 06:28:34 +00:00
|
|
|
.SS Extended security attributes
|
|
|
|
The security attribute namespace is used by kernel security modules,
|
2015-04-22 07:27:03 +00:00
|
|
|
such as Security Enhanced Linux, and also to implement file capabilities (see
|
|
|
|
.BR capabilities (7)).
|
2015-04-22 06:28:34 +00:00
|
|
|
Read and write access permissions to security attributes depend on the
|
|
|
|
policy implemented for each security attribute by the security module.
|
|
|
|
When no security module is loaded, all processes have read access to
|
|
|
|
extended security attributes, and write access is limited to processes
|
2015-04-22 07:01:08 +00:00
|
|
|
that have the
|
|
|
|
.B CAP_SYS_ADMIN
|
|
|
|
capability.
|
2019-07-01 07:54:42 +00:00
|
|
|
.SS System extended attributes
|
|
|
|
System extended attributes are used by the kernel to store system
|
2015-04-22 07:27:03 +00:00
|
|
|
objects such as Access Control Lists.
|
2015-04-22 06:50:55 +00:00
|
|
|
Read and write
|
2015-04-22 06:28:34 +00:00
|
|
|
access permissions to system attributes depend on the policy implemented
|
|
|
|
for each system attribute implemented by filesystems in the kernel.
|
|
|
|
.SS Trusted extended attributes
|
|
|
|
Trusted extended attributes are visible and accessible only to processes that
|
2015-04-22 07:01:08 +00:00
|
|
|
have the
|
|
|
|
.B CAP_SYS_ADMIN
|
2015-04-22 07:33:49 +00:00
|
|
|
capability.
|
2015-04-22 06:28:34 +00:00
|
|
|
Attributes in this class are used to implement mechanisms in user
|
|
|
|
space (i.e., outside the kernel) which keep information in extended attributes
|
|
|
|
to which ordinary processes should not have access.
|
2019-07-01 07:52:41 +00:00
|
|
|
.SS User extended attributes
|
|
|
|
User extended attributes may be assigned to files and directories for
|
2015-04-22 06:28:34 +00:00
|
|
|
storing arbitrary additional information such as the mime type,
|
2015-04-22 06:50:55 +00:00
|
|
|
character set or encoding of a file.
|
|
|
|
The access permissions for user
|
2015-04-22 07:42:32 +00:00
|
|
|
attributes are defined by the file permission bits:
|
|
|
|
read permission is required to retrieve the attribute value,
|
|
|
|
and writer permission is required to change it.
|
2015-04-22 06:28:34 +00:00
|
|
|
.PP
|
|
|
|
The file permission bits of regular files and directories are
|
|
|
|
interpreted differently from the file permission bits of special files
|
2015-04-22 06:50:55 +00:00
|
|
|
and symbolic links.
|
|
|
|
For regular files and directories the file
|
2015-04-22 06:28:34 +00:00
|
|
|
permission bits define access to the file's contents, while for device special
|
|
|
|
files they define access to the device described by the special file.
|
2015-04-22 06:50:55 +00:00
|
|
|
The file permissions of symbolic links are not used in access checks.
|
|
|
|
These differences would allow users to consume filesystem resources in
|
|
|
|
a way not controllable by disk quotas for group or world writable
|
|
|
|
special files and directories.
|
2015-04-22 06:28:34 +00:00
|
|
|
.PP
|
2015-04-22 06:50:55 +00:00
|
|
|
For this reason,
|
2019-07-01 07:52:41 +00:00
|
|
|
user extended attributes are allowed only for regular files and directories,
|
|
|
|
and access to user extended attributes is restricted to the
|
2015-04-22 06:28:34 +00:00
|
|
|
owner and to users with appropriate capabilities for directories with the
|
|
|
|
sticky bit set (see the
|
|
|
|
.BR chmod (1)
|
2015-04-22 11:44:16 +00:00
|
|
|
manual page for an explanation of the sticky bit).
|
2015-04-22 06:54:38 +00:00
|
|
|
.SS Filesystem differences
|
2015-04-22 06:28:34 +00:00
|
|
|
The kernel and the filesystem may place limits on the maximum number
|
|
|
|
and size of extended attributes that can be associated with a file.
|
2015-04-22 08:06:30 +00:00
|
|
|
The VFS imposes limitations that an attribute names is limited to 255 bytes
|
add_key.2, alloc_hugepages.2, execve.2, fanotify_init.2, getrlimit.2, listxattr.2, mmap.2, shmget.2, malloc.3, random.4, st.4, bootparam.7, epoll.7, keyrings.7, pipe.7, xattr.7: Use non-breaking space for measurement units
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-18 10:28:20 +00:00
|
|
|
and an attribute value is limited to 64\ kB.
|
2015-04-22 11:46:26 +00:00
|
|
|
The list of attribute names that
|
add_key.2, alloc_hugepages.2, execve.2, fanotify_init.2, getrlimit.2, listxattr.2, mmap.2, shmget.2, malloc.3, random.4, st.4, bootparam.7, epoll.7, keyrings.7, pipe.7, xattr.7: Use non-breaking space for measurement units
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-18 10:28:20 +00:00
|
|
|
can be returned is also limited to 64\ kB
|
2015-04-22 13:01:19 +00:00
|
|
|
(see BUGS in
|
|
|
|
.BR listxattr (2)).
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.PP
|
2015-04-22 08:03:37 +00:00
|
|
|
Some filesystems, such as Reiserfs (and, historically, ext2 and ext3),
|
|
|
|
require the filesystem to be mounted with the
|
2015-04-22 06:28:34 +00:00
|
|
|
.B user_xattr
|
2019-07-01 07:52:41 +00:00
|
|
|
mount option in order for user extended attributes to be used.
|
2015-04-22 06:28:34 +00:00
|
|
|
.PP
|
2015-04-22 08:12:43 +00:00
|
|
|
In the current ext2, ext3, and ext4 filesystem implementations,
|
2017-03-17 15:26:54 +00:00
|
|
|
the total bytes used by the names and values of all of a file's
|
2015-04-22 08:12:08 +00:00
|
|
|
extended attributes must fit in a single filesystem block (1024, 2048
|
2015-04-22 06:28:34 +00:00
|
|
|
or 4096 bytes, depending on the block size specified when the
|
|
|
|
filesystem was created).
|
|
|
|
.PP
|
2015-04-22 07:17:52 +00:00
|
|
|
In the Btrfs, XFS, and Reiserfs filesystem implementations, there is no
|
2015-04-22 08:06:30 +00:00
|
|
|
practical limit on the number of extended attributes
|
2015-04-22 06:28:34 +00:00
|
|
|
associated with a file, and the algorithms used to store extended
|
|
|
|
attribute information on disk are scalable.
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.PP
|
2015-04-22 08:31:35 +00:00
|
|
|
In the JFS, XFS, and Reiserfs filesystem implementations,
|
|
|
|
the limit on bytes used in an EA value is the ceiling imposed by the VFS.
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.PP
|
2015-04-22 08:38:31 +00:00
|
|
|
In the Btrfs filesystem implementation,
|
|
|
|
the total bytes used for the name, value, and implementation overhead bytes
|
|
|
|
is limited to the filesystem
|
|
|
|
.I nodesize
|
add_key.2, alloc_hugepages.2, execve.2, fanotify_init.2, getrlimit.2, listxattr.2, mmap.2, shmget.2, malloc.3, random.4, st.4, bootparam.7, epoll.7, keyrings.7, pipe.7, xattr.7: Use non-breaking space for measurement units
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-18 10:28:20 +00:00
|
|
|
value (16\ kB by default).
|
2015-04-22 07:20:43 +00:00
|
|
|
.SH CONFORMING TO
|
|
|
|
Extended attributes are not specified in POSIX.1, but some other systems
|
|
|
|
(e.g., the BSDs and Solaris) provide a similar feature.
|
2015-04-22 07:39:40 +00:00
|
|
|
.SH NOTES
|
2015-04-22 06:28:34 +00:00
|
|
|
Since the filesystems on which extended attributes are stored might also
|
|
|
|
be used on architectures with a different byte order and machine word
|
2015-04-22 07:21:44 +00:00
|
|
|
size, care should be taken to store attribute values in an
|
|
|
|
architecture-independent format.
|
aio.7, arp.7, attributes.7, boot.7, cgroups.7, cpuset.7, credentials.7, fanotify.7, fifo.7, glob.7, hier.7, hostname.7, icmp.7, inode.7, inotify.7, keyrings.7, libc.7, mailaddr.7, mount_namespaces.7, mq_overview.7, nptl.7, numa.7, path_resolution.7, persistent-keyring.7, pid_namespaces.7, pipe.7, pkeys.7, process-keyring.7, pthreads.7, pty.7, random.7, sched.7, sem_overview.7, session-keyring.7, shm_overview.7, signal-safety.7, signal.7, spufs.7, standards.7, symlink.7, termio.7, thread-keyring.7, time.7, unicode.7, user-keyring.7, user-session-keyring.7, user_namespaces.7, utf-8.7, xattr.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2017-08-17 22:59:04 +00:00
|
|
|
.PP
|
2015-04-22 12:35:54 +00:00
|
|
|
This page was formerly named
|
|
|
|
.BR attr (5).
|
2015-04-22 06:52:12 +00:00
|
|
|
.\" .SH AUTHORS
|
|
|
|
.\" Andreas Gruenbacher,
|
|
|
|
.\" .RI < a.gruenbacher@bestbits.at >
|
|
|
|
.\" and the SGI XFS development team,
|
|
|
|
.\" .RI < linux-xfs@oss.sgi.com >.
|
2015-04-22 06:28:34 +00:00
|
|
|
.SH SEE ALSO
|
2020-05-19 05:23:34 +00:00
|
|
|
.BR attr (1),
|
2015-04-22 07:01:08 +00:00
|
|
|
.BR getfattr (1),
|
2015-04-22 07:11:27 +00:00
|
|
|
.BR setfattr (1),
|
|
|
|
.BR getxattr (2),
|
2017-03-17 18:26:49 +00:00
|
|
|
.BR ioctl_iflags (2),
|
2015-04-22 07:11:27 +00:00
|
|
|
.BR listxattr (2),
|
|
|
|
.BR removexattr (2),
|
|
|
|
.BR setxattr (2),
|
|
|
|
.BR acl (5),
|
2020-05-16 23:34:25 +00:00
|
|
|
.BR capabilities (7),
|
2018-02-21 07:43:14 +00:00
|
|
|
.BR selinux (8)
|