1fsattr(5) Standards, Environments, and Macros fsattr(5)
2
6 fsattr - extended file attributes
7
9 Attributes are logically supported as files within the file system.
10 The file system is therefore augmented with an orthogonal name space of
11 file attributes. Any file (including attribute files) can have an arbi‐
12 trarily deep attribute tree associated with it. Attribute values are
13 accessed by file descriptors obtained through a special attribute
14 interface. This logical view of "attributes as files" allows the
15 leveraging of existing file system interface functionality to support
16 the construction, deletion, and manipulation of attributes.
17 The special files "." and ".." retain their accustomed semantics within
20 the attribute hierarchy. The "." attribute file refers to the current
21 directory and the ".." attribute file refers to the parent directory.
22 The unnamed directory at the head of each attribute tree is considered
23 the "child" of the file it is associated with and the ".." file refers
24 to the associated file. For any non-directory file with attributes, the
25 ".." entry in the unnamed directory refers to a file that is not a
26 directory.
27 Conceptually, the attribute model is fully general. Extended attributes
30 can be any type of file (doors, links, directories, and so forth) and
31 can even have their own attributes (fully recursive). As a result, the
32 attributes associated with a file could be an arbitrarily deep direc‐
33 tory hierarchy where each attribute could have an equally complex
34 attribute tree associated with it. Not all implementations are able
35 to, or want to, support the full model. Implementation are therefore
36 permitted to reject operations that are not supported. For example,
37 the implementation for the UFS file system allows only regular files as
38 attributes (for example, no sub-directories) and rejects attempts to
39 place attributes on attributes.
40 The following list details the operations that are rejected in the cur‐
43 rent implementation:
44 link Any attempt to create links between attribute
46 and non-attribute space is rejected to prevent
47 security-related or otherwise sensitive
48 attributes from being exposed, and therefore
49 manipulable, as regular files.
50 rename Any attempt to rename between attribute and
53 non-attribute space is rejected to prevent an
54 already linked file from being renamed and
55 thereby circumventing the link restriction
56 above.
57 mkdir, symlink, mknod Any attempt to create a "non-regular" file in
60 attribute space is rejected to reduce the
61 functionality, and therefore exposure and
62 risk, of the initial implementation.
63 The entire available name space has been allocated to "general use" to
67 bring the implementation in line with the NFSv4 draft standard [NFSv4].
68 That standard defines "named attributes" (equivalent to Solaris
69 Extended Attributes) with no naming restrictions. All Sun applications
70 making use of opaque extended attributes will use the prefix "SUNW".
71 Shell-level API
73 The command interface for extended attributes is the set of applica‐
74 tions provided by Solaris for the manipulation of attributes from the
75 command line. This interface consists of a set of existing utilities
76 that have been extended to be "attribute-aware", plus the runat utility
77 designed to "expose" the extended attribute space so that extended
78 attributes can be manipulated as regular files.
79 The -@ option enable utilities to manipulate extended attributes. As a
82 rule, this option enables the utility to enter into attribute space
83 when the utility is performing a recursive traversal of file system
84 space. This is a fully recursive concept. If the underlying file system
85 supports recursive attributes and directory structures, the -@ option
86 opens these spaces to the file tree-walking algorithms.
87 The following utilities accommodate extended attributes (see the indi‐
90 vidual manual pages for details):
91 cp By default, cp ignores attributes and copies only file data.
93 This is intended to maintain the semantics implied by cp cur‐
94 rently, where attributes (such as owner and mode) are not
95 copied unless the -p option is specified. With the -@ (or -p)
96 option, cp attempts to copy all attributes along with the file
97 data.
98 cpio The -@ option informs cpio to archive attributes, but by
101 default cpio ignores extended attributes. See Extended Archive
102 Formats below for a description of the new archive records.
103 du File sizes computed include the space allocated for any
106 extended attributes present.
107 find By default, find ignores attributes. The -xattr expression
110 provides support for searches involving attribute space. It
111 returns true if extended attributes are present on the current
112 file.
113 fsck The fsck utility manages extended attribute data on the disk. A
116 file system with extended attributes can be mounted on versions
117 of Solaris that are not attribute-aware (versions prior to
118 Solaris 9), but the attributes will not be accessible and fsck
119 will strip them from the files and place them in lost+found.
120 Once the attributes have been stripped the file system is com‐
121 pletely stable on Solaris versions that are not attribute-
122 aware, but would now be considered corrupted on attribute-aware
123 versions of Solaris. The attribute-aware fsck utility should be
124 run to stabilize the file system before using it in an
125 attribute-aware environment.
126 fsdb This fsdb utility is able to find the inode for the "hidden"
129 extended attribute directory.
130 ls The ls -@ command displays an "@" following the mode informa‐
133 tion when extended attributes are present. More precisely, the
134 output line for a given file contains an "@" character follow‐
135 ing the mode characters if the pathconf(2) variable
136 XATTR_EXISTS is set to true. See the pathconf() section below.
137 The -@ option uses the same general output format as the -l
138 option.
139 mv When a file is moved, all attributes are carried along with the
142 file rename. When a file is moved across a file system bound‐
143 ary, the copy command invoked is similar to the cp -p variant
144 described above and extended attributes are "moved". If the
145 extended file attributes cannot be replicated, the move opera‐
146 tion fails and the source file is not removed.
147 pax The -@ option informs pax to archive attributes, but by default
150 pax ignores extended attributes. The pax(1) utility is a
151 generic replacement for both tar(1) and cpio(1) and is able to
152 produce either output format in its archive. See Extended Ar‐
153 chive Formats below for a description of the new archive
154 records.
155 tar In the default case, tar does not attempt to place attributes
158 in the archive. If the -@ option is specified, however, tar
159 traverses into the attribute space of all files being placed in
160 the archive and attempts to add the attributes to the archive.
161 A new record type has been introduced for extended attribute
162 entries in tar archive files (the same is true for pax and cpio
163 archives) similar to the way ACLs records were defined. See
164 Extended Archive Formats below for a description of the new ar‐
165 chive records.
166 There is a class of utilities (chmod, chown, chgrp) that one might
170 expect to be modified in a manner similar to those listed above. For
171 example, one might expect that performing chmod on a file would not
172 only affect the file itself but would also affect at least the extended
173 attribute directory if not any existing extended attribute files. This
174 is not the case. The model chosen for extended attributes implies that
175 the attribute directory and the attributes themselves are all file
176 objects in their own right, and can therefore have independent file
177 status attributes associated with them (a given implementation cannot
178 support this, for example, for intrinsic attributes). The relationship
179 is left undefined and a fine-grained control mechanism (runat(1)) is
180 provided to allow manipulation of extended attribute status attributes
181 as necessary.
182 The runat utility has the following syntax:
185 runat filename [command]
187 The runat utility executes the supplied command in the context of the
192 "attribute space" associated with the indicated file. If no command
193 argument is supplied, a shell is invoked. See runat(1) for details.
194 Application-level API
196 The primary interface required to access extended attributes at the
197 programmatic level is the openat(2) function. Once a file descriptor
198 has been obtained for an attribute file by an openat() call, all normal
199 file system semantics apply. There is no attempt to place special
200 semantics on read(2), write(2), ftruncate(3C), or other functions when
201 applied to attribute file descriptors relative to "normal" file
202 descriptors.
203 The set of existing attributes can be browsed by calling openat() with
206 "." as the file name and the O_XATTR flag set, resulting in a file
207 descriptor for the attribute directory. The list of attributes is
208 obtained by calls to getdents(2) on the returned file descriptor. If
209 the target file did not previously have any attributes associated with
210 it, an empty top-level attribute directory is created for the file and
211 subsequent getdents() calls will return only "." and "..". While the
212 owner of the parent file owns the extended attribute directory, it is
213 not charged against its quota if the directory is empty. Attribute
214 files themselves, however, are charged against the user quota as any
215 other regular file.
216 Additional system calls have been provided as convenience functions.
219 These include the fchownat(2), fstatat(2), futimesat(2), renameat(2),
220 unlinkat(2). These new functions, along with openat(), provide a mecha‐
221 nism to access files relative to an arbitrary point in the file system,
222 rather than only the current working directory. This mechanism is par‐
223 ticularly useful in situations when a file descriptor is available with
224 no path. The openat() function, in particular, can be used in many con‐
225 texts where chdir() or fchdir() is currently required. See chdir(2).
226 Open a file relative to a file descriptor
228 int openat (int fd, const char *path, int oflag [, mode_t mode])
229 The openat(2) function behaves exactly as open(2) except when given a
233 relative path. Where open() resolves a relative path from the current
234 working directory, openat() resolves the path based on the vnode indi‐
235 cated by the supplied file descriptor. When oflag is O_XATTR, openat()
236 interprets the path argument as an extended attribute reference. The
237 following code fragment uses openat() to examine the attributes of some
238 already opened file:
239 dfd = openat(fd, ".", O_RDONLY|O_XATTR);
241 (void)getdents(dfd, buf, nbytes);
242 If openat() is passed the special value AT_FDCWD as its first (fd)
246 argument, its behavior is identical to open() and the relative path
247 arguments are interpreted relative to the current working directory. If
248 the O_XATTR flag is provided to openat() or to open(), the supplied
249 path is interpreted as a reference to an extended attribute on the cur‐
250 rent working directory.
251 Unlink a file relative to a directory file descriptor
253 int unlinkat (int dirfd, const char *pathflag, int flagflag)
254 The unlinkat(2) function deletes an entry from a directory. The path
258 argument indicates the name of the entry to remove. If path an absolute
259 path, the dirfd argument is ignored. If it is a relative path, it is
260 interpreted relative to the directory indicated by the dirfd argument.
261 If dirfd does not refer to a valid directory, the function returns
262 ENOTDIR. If the special value AT_FDCWD is specified for dirfd, a rela‐
263 tive path argument is resolved relative to the current working direc‐
264 tory. If the flag argument is 0, all other semantics of this function
265 are equivalent to unlink(2). If flag is set to AT_REMOVEDIR, all other
266 semantics of this function are equivalent to rmdir(2).
267 Rename a file relative to directories
269 int renameat (int fromfd, const char *old, int tofd, const char *new)
270 The renameat(2) function renames an entry in a directory, possibly mov‐
274 ing the entry into a different directory. The old argument indicates
275 the name of the entry to rename. If this argument is a relative path,
276 it is interpreted relative to the directory indicated by the fd argu‐
277 ment. If it is an absolute path, the fromfd argument is ignored. The
278 new argument indicates the new name for the entry. If this argument is
279 a relative path, it is interpreted relative to the directory indicated
280 by the tofd argument. If it is an absolute path, the tofd argument is
281 ignored.
282 In the relative path cases, if the directory file descriptor arguments
285 do not refer to a valid directory, the function returns ENOTDIR. All
286 other semantics of this function are equivalent to rename(2).
287 If a special value AT_FDCWD is specified for either the fromfd or tofd
290 arguments, their associated path arguments (old and new) are inter‐
291 preted relative to the current working directory if they are not speci‐
292 fied as absolute paths. Any attempt to use renameat() to move a file
293 that is not an extended attribute into an extended attribute directory
294 (so that it becomes an extended attribute) will fail. The same is true
295 for an attempt to move a file that is an extended attribute into a
296 directory that is not an extended attribute directory.
297 Obtain information about a file
299 int fstatat (int fd, const char *path, struct stat* buf, int flag)
300 The fstatat(2) function obtains information about a file. If the path
304 argument is relative, it is resolved relative to the fd argument file
305 descriptor, otherwise the fd argument is ignored. If the fd argument
306 is a special value AT_FDCWD the path is resolved relative to the cur‐
307 rent working directory. If the path argument is a null pointer, the
308 function returns information about the file referenced by the fd argu‐
309 ment. In all other relative path cases, if the fd argument does not
310 refer to a valid directory, the function returns ENOTDIR. If AT_SYM‐
311 LINK_NOFOLLOW is set in the flag argument, the function will not auto‐
312 matically traverse a symbolic link at the position of the path. If
313 _AT_TRIGGER is set in the flag argument and the vnode is a trigger
314 mount point, the mount is performed and the function returns the
315 attributes of the root of the mounted filesystem. The fstatat() func‐
316 tion is a multipurpose function that can be used in place of stat(),
317 lstat(), or fstat(). See stat(2)
318 The function call stat(path, buf) is identical to fstatat(AT_FDCWD,
321 path, buf, 0).
322 The function call lstat(path, buf) is identical to fstatat(AT_FDCWD,
325 path, buf, AT_SYMLINK_NOFOLLOW)
326 The function call fstat(fildes, buf) is identical to fstatat(fildes,
329 NULL, buf, 0).
330 Set owner and group ID
332 int fchownat (int fd, const char *path, uid_t owner, gid_t group, \
333 int flag)
334 The fchownat(2) function sets the owner ID and group ID for a file. If
338 the path argument is relative, it is resolved relative to the fd argu‐
339 ment file descriptor, otherwise the fd argument is ignored. If the fd
340 argument is a special value AT_FDCWD the path is resolved relative to
341 the current working directory. If the path argument is a null pointer,
342 the function sets the owner and group ID of the file referenced by the
343 fd argument. In all other relative path cases, if the fd argument does
344 not refer to a valid directory, the function returns ENOTDIR. If the
345 flag argument is set to AT_SYMLINK_NOFOLLOW, the function will not
346 automatically traverse a symbolic link at the position of the path. The
347 fchownat() function is a multi-purpose function that can be used in
348 place of chown(), lchown(), or fchown(). See chown(2).
349 The function call chown(path, owner, group) is equivalent to fchow‐
352 nat(AT_FDCWD, path, owner, group, 0).
353 The function call lchown(path, owner, group) is equivalent to fchow‐
356 nat(AT_FDCWD, path, owner, group, AT_SYMLINK_NOFOLLOW).
357 Set file access and modification times
359 int futimesat (int fd, const char *path, const struct timeval \
360 times[2])
361 The futimesat(2) function sets the access and modification times for a
365 file. If the path argument is relative, it is resolved relative to the
366 fd argument file descriptor; otherwise the fd argument is ignored. If
367 the fd argument is the special value AT_FDCWD, the path is resolved
368 relative to the current working directory. If the path argument is a
369 null pointer, the function sets the access and modification times of
370 the file referenced by the fd argument. In all other relative path
371 cases, if the fd argument does not refer to a valid directory, the
372 function returns ENOTDIR. The futimesat() function can be used in
373 place of utimes(2).
374 The function call utimes(path, times) is equivalent to futime‐
377 sat(AT_FDCWD, path, times).
378 New pathconf() functionality
380 long int pathconf(const char *path, int name)
381 Two variables have been added to pathconf(2) to provide enhanced sup‐
385 port for extended attribute manipulation. The XATTR_ENABLED variable
386 allows an application to determine if attribute support is currently
387 enabled for the file in question. The XATTR_EXISTS variable allows an
388 application to determine whether there are any extended attributes
389 associated with the supplied path.
390 Open/Create an attribute file
392 int attropen (const char *path, const char *attrpath, int oflag \
393 [, mode_t mode])
394 The attropen(3C) function returns a file descriptor for the named
398 attribute, attrpath, of the file indicated by path. The oflag and mode
399 arguments are identical to the open(2) arguments and are applied to the
400 open operation on the attribute file (for example, using the O_CREAT
401 flag creates a new attribute). Once opened, all normal file system
402 operations can be used on the attribute file descriptor. The
403 attropen() function is a convenience function and is equivalent to the
404 following sequence of operations:
405 fd = open (path, O_RDONLY);
407 attrfd = openat(fd, attrpath, oflag|O_XATTR, mode);
408 close(fd);
409 The set of existing attributes can be browsed by calling attropen()
413 with "." as the attribute name. The list of attributes is obtained by
414 calling getdents(2) (or fdopendir(3C) followed by readdir(3C), see
415 below) on the returned file descriptor.
416 Convert an open file descriptor for a directory into a directory descriptor
418 DIR * fdopendir (const int fd)
419 The fdopendir(3C) function promotes a file descriptor for a directory
423 to a directory pointer suitable for use with the readdir(3C) function.
424 The originating file descriptor should not be used again following the
425 call to fdopendir(). The directory pointer should be closed with a call
426 to closedir(3C). If the provided file descriptor does not reference a
427 directory, the function returns ENOTDIR. This function is useful in
428 circumstances where the only available handle on a directory is a file
429 descriptor. See attropen(3C) and openat(2).
430 Using the API
432 The following examples demonstrate how the API might be used to perform
433 basic operations on extended attributes:
434 Example 1 List extended attributes on a file.
436 attrdirfd = attropen("test", ".", O_RDONLY);
438 dirp = fdopendir(attrdirfd);
439 while (dp = readdir(dirp)) {
440 ...
441 Example 2 Open an extended attribute.
444 attrfd = attropen("test", dp->d_name, O_RDONLY);
446 or
450 attrfd = openat(attrdirfd, dp->d_name, O_RDONLY);
453 Example 3 Read from an extended attribute.
456 while (read(attrfd, buf, 512) > 0) {
458 ...
459 Example 4 Create an extended attribute.
462 newfd = attropen("test", "attr", O_CREAT|O_RDWR);
464 or
468 newfd = openat(attrdirfd, "attr", O_CREAT|O_RDWR);
471 Example 5 Write to an extended attribute.
474 count = write(newfd, buf, length);
476 Example 6 Delete an extended attribute.
479 error = unlinkat(attrdirfd, "attr");
481 Applications intending to access the interfaces defined here as well as
485 the POSIX and X/Open specification-conforming interfaces should define
486 the macro _ATFILE_SOURCE to be 1 and set whichever feature test macros
487 are appropriate to obtain the desired environment. See standards(5).
488 Extended Archive Formats
490 As noted above in the description of command utilities modified to pro‐
491 vide support for extended attributes, the archive formats for tar(1)
492 and cpio(1) have been extended to provide support for archiving
493 extended attributes. This section describes the specifics of the ar‐
494 chive format extensions.
495 Extended tar format
497 The tar archive is made up of a series of 512 byte blocks. Each
498 archived file is represented by a header block and zero or more data
499 blocks containing the file contents. The header block is structured as
500 shown in the following table.
501 Field Name Length (in Octets) Description
506 Name 100 File name string
507 Mode 8 12 file mode bits
508 Uid 8 User ID of file owner
509 Gid 8 Group ID of file owner
510 Size 12 Size of file
511 Mtime 12 File modification time
512 Chksum 8 File contents checksum
513 Typeflag 1 File type flag
514 Linkname 100 Link target name if file linked
515 Magic 6 "ustar"
516 Version 2 "00"
517 Uname 32 User name of file owner
518 Gname 32 Group name of file owner
519 Devmajor 8 Major device ID if special file
520 Devminor 8 Minor device ID if special file
521 Prefix 155 Path prefix string for file
522 The extended attribute project extends the above header format by
526 defining a new header type (for the Typeflag field). The type 'E' is
527 defined to be used for all extended attribute files. Attribute files
528 are stored in the tar archive as a sequence of two <header ,data>
529 pairs. The first file contains the data necessary to locate and name
530 the extended attribute in the file system. The second file contains the
531 actual attribute file data. Both files use an 'E' type header. The
532 prefix and name fields in extended attribute headers are ignored,
533 though they should be set to meaningful values for the benefit of
534 archivers that do not process these headers. Solaris archivers set the
535 prefix field to "/dev/null" to prevent archivers that do not understand
536 the type 'E' header from trying to restore extended attribute files in
537 inappropriate places.
538 Extended cpio format
540 The cpio archive format is octet-oriented rather than block-oriented.
541 Each file entry in the archive includes a header that describes the
542 file, followed by the file name, followed by the contents of the file.
543 These data are arranged as described in the following table.
544 Field Name Length (in Octets) Description
549 c_magic 6 70707
550 c_dev 6 First half of unique file ID
551 c_ino 6 Second half of unique file ID
552 c_mode 6 File mode bits
553 c_uid 6 User ID of file owner
554 c_gid 6 Group ID of file owner
555 c_nlink 6 Number of links referencing file
556 c_rdev 6 Information for special files
557 c_mtime 11 Modification time of file
558 c_namesize 6 Length of file pathname
559 c_filesize 11 Length of file content
560 c_name c_namesize File pathname
561 c_filedata c_filesize File content
562 The basic archive file structure is not changed for extended
566 attributes. The file type bits stored in the c_mode field for an
567 attribute file are set to 0xB000. As with the tar archive format,
568 extended attributes are stored in cpio archives as two consecutive file
569 entries. The first file describes the location/name for the extended
570 attribute. The second file contains the actual attribute file content.
571 The c_name field in extended attribute headers is ignored, though it
572 should be set to a meaningful value for the benefit of archivers that
573 do not process these headers. Solaris archivers start the pathname
574 with "/dev/null/"to prevent archivers that do not understand the type
575 'E' header from trying to restore extended attribute files in inappro‐
576 priate places.
577 Attribute identification data format
579 Both the tar and cpio archive formats can contain the special files
580 described above, always paired with the extended attribute data record,
581 for identifying the precise location of the extended attribute. These
582 special data files are necessary because there is no simple naming
583 mechanism for extended attribute files. Extended attributes are not
584 visible in the file system name space. The extended attribute name
585 space must be "tunneled into" using the openat() function. The
586 attribute identification data must support not only the flat naming
587 structure for extended attributes, but also the possibility of future
588 extensions allowing for attribute directory hierarchies and recursive
589 attributes. The data file is therefore composed of a sequence of
590 records. It begins with a fixed length header describing the content.
591 The following table describes the format of this data file.
592 Field Name Length (in Octets) Description
597 h_version 7 Name file version
598 h_size 10 Length of data file
599 h_component_len 10 Total length of all path segments
600 h_link_comp_len 10 Total length of all link segments
601 path h_component_len Complex path
602 link_path h_link_comp_len Complex link path
603 As demonstrated above, the header is followed by a record describing
607 the "path" to the attribute file. This path is composed of two or more
608 path segments separated by a null character. Each segment describes a
609 path rooted at the hidden extended attribute directory of the leaf file
610 of the previous segment, making it possible to name attributes on
611 attributes. The first segment is always the path to the parent file
612 that roots the entire sequence in the normal name space. The following
613 table describes the format of each segment.
614 Field Name Length (in Octets) Description
619 ───────────────────────────────────────────────────────────────────────────
620 h_namesz 7 Length of segment path
621 h_typeflag 1 Actual file type of attribute file
622 h_names h_namesz Parent path + segment path
623 If the attribute file is linked to another file, the path record is
627 followed by a second record describing the location of the referencing
628 file. The structure of this record is identical to the record
629 described above.
630
632 cp(1), cpio(1), find(1), ls(1), mv(1), pax(1), runat(1), tar(1), du(1),
633 fsck(1M), chown(2), link(2), open(2), pathconf(2), rename(2), stat(2),
634 unlink(2), utimes(2), attropen(3C), standards(5)
635SunOS 5.11 10 Oct 2007 fsattr(5)