]>
Commit | Line | Data |
---|---|---|
544a5910 AG |
1 | .\" Extended attributes manual page |
2 | .\" | |
3 | .\" Copyright (C) 2000, 2002, 2007 Andreas Gruenbacher <agruen@suse.de> | |
4 | .\" Copyright (C) 2001, 2002, 2004, 2007 Silicon Graphics, Inc. | |
5 | .\" All rights reserved. | |
6 | .\" | |
3f3b5c75 | 7 | .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
544a5910 AG |
8 | .\" This is free documentation; you can redistribute it and/or |
9 | .\" modify it under the terms of the GNU General Public License as | |
10 | .\" published by the Free Software Foundation; either version 2 of | |
11 | .\" the License, or (at your option) any later version. | |
12 | .\" | |
13 | .\" The GNU General Public License's references to "object code" | |
14 | .\" and "executables" are to be interpreted as the output of any | |
15 | .\" document formatting or typesetting system, including | |
16 | .\" intermediate and printed output. | |
17 | .\" | |
18 | .\" This manual is distributed in the hope that it will be useful, | |
19 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
20 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
21 | .\" GNU General Public License for more details. | |
22 | .\" | |
23 | .\" You should have received a copy of the GNU General Public | |
24 | .\" License along with this manual. If not, see | |
25 | .\" <http://www.gnu.org/licenses/>. | |
3f3b5c75 | 26 | .\" %%%LICENSE_END |
544a5910 | 27 | .\" |
09b8afdc | 28 | .TH XATTR 7 2018-04-30 "Linux" "Linux Programmer's Manual" |
544a5910 | 29 | .SH NAME |
bbbaa1f6 | 30 | xattr \- Extended attributes |
544a5910 AG |
31 | .SH DESCRIPTION |
32 | Extended attributes are name:value pairs associated permanently with | |
33 | files and directories, similar to the environment strings associated | |
34 | with a process. | |
35 | An attribute may be defined or undefined. | |
36 | If it is defined, its value may be empty or non-empty. | |
37 | .PP | |
38 | Extended attributes are extensions to the normal attributes which are | |
ebce8403 | 39 | associated with all inodes in the system (i.e., the |
544a5910 AG |
40 | .BR stat (2) |
41 | data). | |
42 | They are often used to provide additional functionality | |
ca7d9e34 | 43 | to a filesystem\(emfor example, additional security features such as |
544a5910 AG |
44 | Access Control Lists (ACLs) may be implemented using extended attributes. |
45 | .PP | |
d59b17a4 MK |
46 | Users with search access to a file or directory may use |
47 | .BR listxattr (2) | |
48 | to retrieve a list of attribute names defined for that file or directory. | |
544a5910 AG |
49 | .PP |
50 | Extended attributes are accessed as atomic objects. | |
d59b17a4 MK |
51 | Reading |
52 | .RB ( getxattr (2)) | |
53 | retrieves the whole value of an attribute and stores it in a buffer. | |
54 | Writing | |
55 | .RB ( setxattr (2)) | |
56 | replaces any previous value with the new value. | |
544a5910 | 57 | .PP |
54015724 | 58 | Space consumed for extended attributes may be counted towards the disk quotas |
544a5910 | 59 | of the file owner and file group. |
b63436d8 | 60 | .SS Extended attribute namespaces |
68d53b6d | 61 | Attribute names are null-terminated strings. |
544a5910 AG |
62 | The attribute name is always specified in the fully qualified |
63 | .IR namespace.attribute | |
ebce8403 | 64 | form, for example, |
544a5910 AG |
65 | .IR user.mime_type , |
66 | .IR trusted.md5sum , | |
67 | .IR system.posix_acl_access , | |
68 | or | |
69 | .IR security.selinux . | |
70 | .PP | |
71 | The namespace mechanism is used to define different classes of extended | |
72 | attributes. | |
ebce8403 MK |
73 | These different classes exist for several reasons; |
74 | for example, the permissions | |
544a5910 AG |
75 | and capabilities required for manipulating extended attributes of one |
76 | namespace may differ to another. | |
77 | .PP | |
ca7d9e34 | 78 | Currently, the |
544a5910 AG |
79 | .IR security , |
80 | .IR system , | |
81 | .IR trusted , | |
82 | and | |
83 | .IR user | |
933e4675 MK |
84 | extended attribute classes are defined as described below. |
85 | Additional classes may be added in the future. | |
544a5910 AG |
86 | .SS Extended security attributes |
87 | The security attribute namespace is used by kernel security modules, | |
d8ba7694 MK |
88 | such as Security Enhanced Linux, and also to implement file capabilities (see |
89 | .BR capabilities (7)). | |
544a5910 AG |
90 | Read and write access permissions to security attributes depend on the |
91 | policy implemented for each security attribute by the security module. | |
92 | When no security module is loaded, all processes have read access to | |
93 | extended security attributes, and write access is limited to processes | |
5ee7f61c MK |
94 | that have the |
95 | .B CAP_SYS_ADMIN | |
96 | capability. | |
544a5910 AG |
97 | .SS Extended system attributes |
98 | Extended system attributes are used by the kernel to store system | |
d8ba7694 | 99 | objects such as Access Control Lists. |
933e4675 | 100 | Read and write |
544a5910 AG |
101 | access permissions to system attributes depend on the policy implemented |
102 | for each system attribute implemented by filesystems in the kernel. | |
103 | .SS Trusted extended attributes | |
104 | Trusted extended attributes are visible and accessible only to processes that | |
5ee7f61c MK |
105 | have the |
106 | .B CAP_SYS_ADMIN | |
b4a61f89 | 107 | capability. |
544a5910 AG |
108 | Attributes in this class are used to implement mechanisms in user |
109 | space (i.e., outside the kernel) which keep information in extended attributes | |
110 | to which ordinary processes should not have access. | |
111 | .SS Extended user attributes | |
112 | Extended user attributes may be assigned to files and directories for | |
113 | storing arbitrary additional information such as the mime type, | |
933e4675 MK |
114 | character set or encoding of a file. |
115 | The access permissions for user | |
03a93c37 MK |
116 | attributes are defined by the file permission bits: |
117 | read permission is required to retrieve the attribute value, | |
118 | and writer permission is required to change it. | |
544a5910 AG |
119 | .PP |
120 | The file permission bits of regular files and directories are | |
121 | interpreted differently from the file permission bits of special files | |
933e4675 MK |
122 | and symbolic links. |
123 | For regular files and directories the file | |
544a5910 AG |
124 | permission bits define access to the file's contents, while for device special |
125 | files they define access to the device described by the special file. | |
933e4675 MK |
126 | The file permissions of symbolic links are not used in access checks. |
127 | These differences would allow users to consume filesystem resources in | |
128 | a way not controllable by disk quotas for group or world writable | |
129 | special files and directories. | |
544a5910 | 130 | .PP |
933e4675 | 131 | For this reason, |
355657c2 | 132 | extended user attributes are allowed only for regular files and directories, |
933e4675 | 133 | and access to extended user attributes is restricted to the |
544a5910 AG |
134 | owner and to users with appropriate capabilities for directories with the |
135 | sticky bit set (see the | |
136 | .BR chmod (1) | |
54015724 | 137 | manual page for an explanation of the sticky bit). |
b63436d8 | 138 | .SS Filesystem differences |
544a5910 AG |
139 | The kernel and the filesystem may place limits on the maximum number |
140 | and size of extended attributes that can be associated with a file. | |
6db035a3 | 141 | The VFS imposes limitations that an attribute names is limited to 255 bytes |
c4b7e5ac | 142 | and an attribute value is limited to 64\ kB. |
5c69f84a | 143 | The list of attribute names that |
c4b7e5ac | 144 | can be returned is also limited to 64\ kB |
92b1a2cc MK |
145 | (see BUGS in |
146 | .BR listxattr (2)). | |
a721e8b2 | 147 | .PP |
9a7d1c23 MK |
148 | Some filesystems, such as Reiserfs (and, historically, ext2 and ext3), |
149 | require the filesystem to be mounted with the | |
544a5910 AG |
150 | .B user_xattr |
151 | mount option in order for extended user attributes to be used. | |
152 | .PP | |
3d33987b | 153 | In the current ext2, ext3, and ext4 filesystem implementations, |
74532967 | 154 | the total bytes used by the names and values of all of a file's |
6ad46a9d | 155 | extended attributes must fit in a single filesystem block (1024, 2048 |
544a5910 AG |
156 | or 4096 bytes, depending on the block size specified when the |
157 | filesystem was created). | |
158 | .PP | |
b68d4dc3 | 159 | In the Btrfs, XFS, and Reiserfs filesystem implementations, there is no |
6db035a3 | 160 | practical limit on the number of extended attributes |
544a5910 AG |
161 | associated with a file, and the algorithms used to store extended |
162 | attribute information on disk are scalable. | |
a721e8b2 | 163 | .PP |
edb159da MK |
164 | In the JFS, XFS, and Reiserfs filesystem implementations, |
165 | the limit on bytes used in an EA value is the ceiling imposed by the VFS. | |
a721e8b2 | 166 | .PP |
7f4f24ea MK |
167 | In the Btrfs filesystem implementation, |
168 | the total bytes used for the name, value, and implementation overhead bytes | |
169 | is limited to the filesystem | |
170 | .I nodesize | |
c4b7e5ac | 171 | value (16\ kB by default). |
b124a27b MK |
172 | .SH CONFORMING TO |
173 | Extended attributes are not specified in POSIX.1, but some other systems | |
174 | (e.g., the BSDs and Solaris) provide a similar feature. | |
7ee629ab | 175 | .SH NOTES |
544a5910 AG |
176 | Since the filesystems on which extended attributes are stored might also |
177 | be used on architectures with a different byte order and machine word | |
5871fb36 MK |
178 | size, care should be taken to store attribute values in an |
179 | architecture-independent format. | |
a721e8b2 | 180 | .PP |
367f5ee5 MK |
181 | This page was formerly named |
182 | .BR attr (5). | |
31a369b8 MK |
183 | .\" .SH AUTHORS |
184 | .\" Andreas Gruenbacher, | |
185 | .\" .RI < a.gruenbacher@bestbits.at > | |
186 | .\" and the SGI XFS development team, | |
187 | .\" .RI < linux-xfs@oss.sgi.com >. | |
544a5910 | 188 | .SH SEE ALSO |
5ee7f61c | 189 | .BR getfattr (1), |
aad5c297 MK |
190 | .BR setfattr (1), |
191 | .BR getxattr (2), | |
c05935a2 | 192 | .BR ioctl_iflags (2), |
aad5c297 MK |
193 | .BR listxattr (2), |
194 | .BR removexattr (2), | |
195 | .BR setxattr (2), | |
196 | .BR acl (5), | |
197 | .BR capabilities (7) | |
9863b9ac | 198 | .BR selinux (8) |