Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
fsattr(5)	      Standards, Environments, and Macros	     fsattr(5)

NAME
       fsattr -	extended file attributes

DESCRIPTION
       Attributes  are	logically  supported  as files within the file system.
       The file	system is therefore augmented with an orthogonal name space of
       file attributes.	Any file (including attribute files) can have an arbi-
       trarily deep attribute tree associated with it.	Attribute  values  are
       accessed	 by  file descriptors obtained through a special attribute in-
       terface.	 This logical view of "attributes as files" allows the	lever-
       aging  of  existing  file system	interface functionality	to support the
       construction, deletion, and manipulation	of attributes.

       The special files "." and ".." retain their accustomed semantics	within
       the  attribute hierarchy.  The "." attribute file refers	to the current
       directory and the ".." attribute	file refers to the  parent  directory.
       The  unnamed directory at the head of each attribute tree is considered
       the "child" of the file it is associated	with and the ".." file	refers
       to the associated file. For any non-directory file with attributes, the
       ".." entry in the unnamed directory refers to a file that is not	a  di-
       rectory.

       Conceptually, the attribute model is fully general. Extended attributes
       can be any type of file (doors, links, directories, and so  forth)  and
       can even	have their own attributes (fully recursive).  As a result, the
       attributes associated with a file could be an arbitrarily  deep	direc-
       tory  hierarchy	where each attribute could have	an equally complex at-
       tribute tree associated with it.	 Not all implementations are able  to,
       or  want	 to, support the full model. Implementation are	therefore per-
       mitted to reject	operations that	are not	supported.  For	 example,  the
       implementation for the UFS file system allows only regular files	as at-
       tributes	(for example, no  sub-directories)  and	 rejects  attempts  to
       place attributes	on attributes.

       The following list details the operations that are rejected in the cur-
       rent implementation:

       link		       Any attempt to create links  between  attribute
			       and  non-attribute space	is rejected to prevent
			       security-related	 or  otherwise	sensitive  at-
			       tributes	 from being exposed, and therefore ma-
			       nipulable, as regular files.

       rename		       Any attempt to  rename  between	attribute  and
			       non-attribute  space  is	rejected to prevent an
			       already linked  file  from  being  renamed  and
			       thereby	 circumventing	the  link  restriction
			       above.

       mkdir, symlink, mknod   Any attempt to create a "non-regular"  file  in
			       attribute space is rejected to reduce the func-
			       tionality, and therefore	exposure and risk,  of
			       the initial implementation.

       The  entire available name space	has been allocated to "general use" to
       bring the implementation	in line	with the NFSv4 draft standard [NFSv4].
       That  standard  defines	"named	attributes" (equivalent	to Solaris Ex-
       tended Attributes) with no naming restrictions.	All  Sun  applications
       making use of opaque extended attributes	will use the prefix "SUNW".

   Shell-level API
       The  command  interface	for extended attributes	is the set of applica-
       tions provided by Solaris for the manipulation of attributes  from  the
       command	line.  This  interface consists	of a set of existing utilities
       that have been extended to be "attribute-aware",	plus the runat utility
       designed	 to "expose" the extended attribute space so that extended at-
       tributes	can be manipulated as regular files.

       The -@ option enable utilities to manipulate extended attributes. As  a
       rule,  this  option  enables  the utility to enter into attribute space
       when the	utility	is performing a	recursive  traversal  of  file	system
       space. This is a	fully recursive	concept. If the	underlying file	system
       supports	recursive attributes and directory structures, the  -@	option
       opens these spaces to the file tree-walking algorithms.

       The  following utilities	accommodate extended attributes	(see the indi-
       vidual manual pages for details):

       cp	       By default, cp ignores attributes and copies only  file
		       data.   This  is	intended to maintain the semantics im-
		       plied by	cp currently, where attributes (such as	 owner
		       and mode) are not copied	unless the -p option is	speci-
		       fied. With the -@ (or -p) option, cp attempts  to  copy
		       all attributes along with the file data.

       cpio	       The  -@	option informs cpio to archive attributes, but
		       by default cpio ignores extended	 attributes.  See  Ex-
		       tended  Archive	Formats	below for a description	of the
		       new archive records.

       du	       File sizes computed include the space allocated for any
		       extended	attributes present.

       find	       By  default,  find  ignores attributes.	The -xattr ex-
		       pression	provides support for searches involving	attri-
		       bute  space. It returns true if extended	attributes are
		       present on the current file.

       fsck	       The fsck	utility	manages	extended attribute data	on the
		       disk.  A	 file  system  with extended attributes	can be
		       mounted on versions of Solaris that are not  attribute-
		       aware (versions prior to	Solaris	9), but	the attributes
		       will not	be accessible and fsck will  strip  them  from
		       the  files  and	place them in lost+found. Once the at-
		       tributes	have been stripped the	file  system  is  com-
		       pletely	stable on Solaris versions that	are not	attri-
		       bute-aware, but would now be  considered	 corrupted  on
		       attribute-aware	versions  of  Solaris.	The attribute-
		       aware fsck utility should be run	to stabilize the  file
		       system  before  using it	in an attribute-aware environ-
		       ment.

       fsdb	       This fsdb utility is able to find  the  inode  for  the
		       "hidden"	extended attribute directory.

       ls	       The  ls	-@  command displays an	"@" following the mode
		       information when	extended attributes are	present.  More
		       precisely, the output line for a	given file contains an
		       "@" character following	the  mode  characters  if  the
		       pathconf(2)  variable  XATTR_EXISTS is set to true. See
		       the pathconf() section below.  The -@ option  uses  the
		       same general output format as the -l option.

       mv	       When  a file is moved, all attributes are carried along
		       with the	file rename. When a file  is  moved  across  a
		       file system boundary, the copy command invoked is simi-
		       lar to the cp -p	variant	described above	 and  extended
		       attributes  are	"moved".   If  the  extended  file at-
		       tributes	cannot be replicated, the move operation fails
		       and the source file is not removed.

       pax	       The -@ option informs pax to archive attributes,	but by
		       default pax ignores extended  attributes.   The	pax(1)
		       utility	is  a  generic replacement for both tar(1) and
		       cpio(1) and is able to produce either output format  in
		       its  archive.  See Extended Archive Formats below for a
		       description of the new archive records.

       tar	       In the default case, tar	does not attempt to place  at-
		       tributes	 in  the  archive.  If the -@ option is	speci-
		       fied, however, tar traverses into the  attribute	 space
		       of  all	files being placed in the archive and attempts
		       to add the attributes to	the archive. A new record type
		       has  been  introduced for extended attribute entries in
		       tar archive files (the same is true for	pax  and  cpio
		       archives) similar to the	way ACLs records were defined.
		       See Extended Archive Formats below for a	description of
		       the new archive records.

       There  is a class of utilities (chmod, chown, chgrp) that one might ex-
       pect to be modified in a	manner similar to those	listed above. For  ex-
       ample,  one might expect	that performing	chmod on a file	would not only
       affect the file itself but would	also affect at least the extended  at-
       tribute	directory  if not any existing extended	attribute files.  This
       is not the case.	 The model chosen for extended attributes implies that
       the  attribute directory	and the	attributes themselves are all file ob-
       jects in	their own right, and can therefore have	independent file  sta-
       tus  attributes	associated  with  them	(a given implementation	cannot
       support this, for example, for intrinsic	attributes).  The relationship
       is  left	 undefined  and	a fine-grained control mechanism (runat(1)) is
       provided	to allow manipulation of extended attribute status  attributes
       as necessary.

       The runat utility has the following syntax:

       runat filename [command]

       The  runat  utility executes the	supplied command in the	context	of the
       "attribute space" associated with the indicated file.   If  no  command
       argument	is supplied, a shell is	invoked. See runat(1) for details.

   Application-level API
       The  primary  interface	required  to access extended attributes	at the
       programmatic level is the openat(2) function. Once  a  file  descriptor
       has been	obtained for an	attribute file by an openat() call, all	normal
       file system semantics apply. There is no	attempt	to place  special  se-
       mantics	on  read(2),  write(2),	ftruncate(3C), or other	functions when
       applied to attribute file descriptors relative  to  "normal"  file  de-
       scriptors.

       The  set	of existing attributes can be browsed by calling openat() with
       "." as the file name and	the O_XATTR flag set, resulting	in a file  de-
       scriptor	 for  the  attribute directory.	 The list of attributes	is ob-
       tained by calls to getdents(2) on the returned file descriptor.	If the
       target  file did	not previously have any	attributes associated with it,
       an empty	top-level attribute directory is created for the file and sub-
       sequent	getdents()  calls  will	 return	 only "." and "..".  While the
       owner of	the parent file	owns the extended attribute directory,	it  is
       not  charged  against  its  quota if the	directory is empty.  Attribute
       files themselves, however, are charged against the user	quota  as  any
       other regular file.

       Additional  system  calls  have been provided as	convenience functions.
       These include the fchownat(2), fstatat(2),  futimesat(2),  renameat(2),
       unlinkat(2). These new functions, along with openat(), provide a	mecha-
       nism to access files relative to	an arbitrary point in the file system,
       rather than only	the current working directory.	This mechanism is par-
       ticularly useful	in situations when a file descriptor is	available with
       no path.	The openat() function, in particular, can be used in many con-
       texts where chdir() or fchdir() is currently required. See chdir(2).

   Open	a file relative	to a file descriptor
       int openat (int fd, const char *path, int oflag [, mode_t mode])

       The openat(2) function behaves exactly as open(2) except	when  given  a
       relative	 path.	Where open() resolves a	relative path from the current
       working directory, openat() resolves the	path based on the vnode	 indi-
       cated  by the supplied file descriptor. When oflag is O_XATTR, openat()
       interprets the path argument as an extended  attribute  reference.  The
       following code fragment uses openat() to	examine	the attributes of some
       already opened file:

       dfd = openat(fd,	".", O_RDONLY|O_XATTR);
       (void)getdents(dfd, buf,	nbytes);

       If openat() is passed the special value AT_FDCWD	as its first (fd)  ar-
       gument, its behavior is identical to open() and the relative path argu-
       ments are interpreted relative to the current working directory.	If the
       O_XATTR flag is provided	to openat() or to open(), the supplied path is
       interpreted as a	reference to an	 extended  attribute  on  the  current
       working directory.

   Unlink a file relative to a directory file descriptor
       int unlinkat (int dirfd,	const char *pathflag, int flagflag)

       The  unlinkat(2)	 function deletes an entry from	a directory.  The path
       argument	indicates the name of the entry	to remove. If path an absolute
       path,  the  dirfd  argument is ignored. If it is	a relative path, it is
       interpreted relative to the directory indicated by the dirfd  argument.
       If  dirfd  does	not  refer  to a valid directory, the function returns
       ENOTDIR.	 If the	special	value AT_FDCWD is specified for	dirfd, a rela-
       tive  path  argument is resolved	relative to the	current	working	direc-
       tory.  If the flag argument is 0, all other semantics of	this  function
       are equivalent to unlink(2).  If	flag is	set to AT_REMOVEDIR, all other
       semantics of this function are equivalent to rmdir(2).

   Rename a file relative to directories
       int renameat (int fromfd, const char *old, int tofd, const char *new)

       The renameat(2) function	renames	an entry in a directory, possibly mov-
       ing  the	 entry into a different	directory.  The	old argument indicates
       the name	of the entry to	rename.	 If this argument is a relative	 path,
       it  is  interpreted relative to the directory indicated by the fd argu-
       ment. If	it is an absolute path,	the fromfd argument is	ignored.   The
       new argument indicates the new name for the entry.  If this argument is
       a relative path,	it is interpreted relative to the directory  indicated
       by  the	tofd argument. If it is	an absolute path, the tofd argument is
       ignored.

       In the relative path cases, if the directory file descriptor  arguments
       do  not	refer to a valid directory, the	function returns ENOTDIR.  All
       other semantics of this function	are equivalent to rename(2).

       If a special value AT_FDCWD is specified	for either the fromfd or  tofd
       arguments,  their  associated  path  arguments (old and new) are	inter-
       preted relative to the current working directory	if they	are not	speci-
       fied  as	 absolute  paths. Any attempt to use renameat()	to move	a file
       that is not an extended attribute into an extended attribute  directory
       (so  that it becomes an extended	attribute) will	fail. The same is true
       for an attempt to move a	file that is an	extended attribute into	a  di-
       rectory that is not an extended attribute directory.

   Obtain information about a file
       int fstatat (int	fd, const char *path, struct stat* buf,	int flag)

       The  fstatat(2) function	obtains	information about a file.  If the path
       argument	is relative, it	is resolved relative to	the fd	argument  file
       descriptor,  otherwise  the fd argument is ignored.  If the fd argument
       is a special value AT_FDCWD the path is resolved	relative to  the  cur-
       rent  working  directory.   If the path argument	is a null pointer, the
       function	returns	information about the file referenced by the fd	 argu-
       ment.   In  all	other relative path cases, if the fd argument does not
       refer to	a valid	directory, the function	returns	ENOTDIR. If  the  flag
       argument	is set to AT_SYMLINK_NOFOLLOW, the function will not automati-
       cally traverse a	symbolic link at the position of  the  path.  The  fs-
       tatat()	function is a multi-purpose function that can be used in place
       of stat(), lstat(), or fstat(). See stat(2).

       The function call stat(path, buf)  is  identical	 to  fstatat(AT_FDCWD,
       path, buf, 0).

       The  function  call  lstat(path,	buf) is	identical to fstatat(AT_FDCWD,
       path, buf, AT_SYMLINK_NOFOLLOW)

       The function call fstat(fildes, buf) is	identical  to  fstatat(fildes,
       NULL, buf, 0).

   Set owner and group ID
       int fchownat (int fd, const char	*path, uid_t owner, gid_t group, int flag)

       The  fchownat(2)	function sets the owner	ID and group ID	for a file. If
       the path	argument is relative, it is resolved relative to the fd	 argu-
       ment  file descriptor, otherwise	the fd argument	is ignored.  If	the fd
       argument	is a special value AT_FDCWD the	path is	resolved  relative  to
       the current working directory.  If the path argument is a null pointer,
       the function sets the owner and group ID	of the file referenced by  the
       fd argument.  In	all other relative path	cases, if the fd argument does
       not refer to a valid directory, the function returns  ENOTDIR.  If  the
       flag  argument is set to	AT_SYMLINK_NOFOLLOW, the function will not au-
       tomatically traverse a symbolic link at the position of the  path.  The
       fchownat()  function  is	 a  multi-purpose function that	can be used in
       place of	chown(), lchown(), or fchown().	See chown(2).

       The function call chown(path, owner, group)  is	equivalent  to	fchow-
       nat(AT_FDCWD, path, owner, group, 0).

       The  function  call  lchown(path, owner,	group) is equivalent to	fchow-
       nat(AT_FDCWD, path, owner, group, AT_SYMLINK_NOFOLLOW).

   Set file access and modification times
       int futimesat (int fd, const char *path,	const struct timeval times[2])

       The futimesat(2)	function sets the access and modification times	for  a
       file.  If the path argument is relative,	it is resolved relative	to the
       fd argument file	descriptor; otherwise the fd argument is ignored.   If
       the  fd	argument  is  the special value	AT_FDCWD, the path is resolved
       relative	to the current working directory.  If the path argument	 is  a
       null  pointer,  the  function sets the access and modification times of
       the file	referenced by the fd argument.	In  all	 other	relative  path
       cases,  if  the	fd  argument  does not refer to	a valid	directory, the
       function	returns	ENOTDIR.
	The futimesat()	function can be	used in	place of utimes(2).

       The function call utimes(path, times) is	equivalent to futimesat(AT_FD-
       CWD, path, times).

   New pathconf() functionality
       long int	pathconf(const char *path, int name)

       Two  variables  have been added to pathconf(2) to provide enhanced sup-
       port for	extended attribute manipulation.  The  XATTR_ENABLED  variable
       allows  an  application	to determine if	attribute support is currently
       enabled for the file in question. The XATTR_EXISTS variable  allows  an
       application  to determine whether there are any extended	attributes as-
       sociated	with the supplied path.

   Open/Create an attribute file
       int attropen (const char	*path, const char *attrpath, int oflag [, mode_t mode])

       The attropen(3C)	function returns a file	descriptor for the  named  at-
       tribute,	attrpath, of the file indicated	by path.
	The  oflag  and	 mode arguments	are identical to the open(2) arguments
       and are applied to the open operation on	the attribute file (for	 exam-
       ple, using the O_CREAT flag creates a new attribute).  Once opened, all
       normal file system operations can be used on  the  attribute  file  de-
       scriptor.   The	attropen()  function  is a convenience function	and is
       equivalent to the following sequence of operations:

       fd = open (path,	O_RDONLY);
       attrfd =	openat(fd, attrpath, oflag|O_XATTR, mode);
       close(fd);

       The set of existing attributes can be  browsed  by  calling  attropen()
       with  "." as the	attribute name.	 The list of attributes	is obtained by
       calling getdents(2) (or fdopendir(3C) followed by readdir(3C), see  be-
       low) on the returned file descriptor.

   Convert an open file	descriptor for a directory into	a directory descriptor
       DIR * fdopendir (const int fd)

       The  fdopendir(3C)  function promotes a file descriptor for a directory
       to a directory pointer suitable for use with the	readdir(3C)  function.
       The  originating	file descriptor	should not be used again following the
       call to fdopendir(). The	directory pointer should be closed with	a call
       to  closedir(3C).  If the provided file descriptor does not reference a
       directory, the function returns ENOTDIR.	This  function	is  useful  in
       circumstances  where the	only available handle on a directory is	a file
       descriptor. See attropen(3C) and	openat(2).

   Using the API
       The following examples demonstrate how the API might be used to perform
       basic operations	on extended attributes:

       Example 1: List extended	attributes on a	file.

       attrdirfd = attropen("test", ".", O_RDONLY);
       dirp = fdopendir(attrdirfd);
       while (dp = readdir(dirp)) {
       ...

       Example 2: Open an extended attribute.

       attrfd =	attropen("test", dp->d_name, O_RDONLY);

       or

       attrfd =	openat(attrdirfd, dp->d_name, O_RDONLY);

       Example 3: Read from an extended	attribute.

       while (read(attrfd, buf,	512) > 0) {
       ...

       Example 4: Create an extended attribute.

       newfd = attropen("test",	"attr",	O_CREAT|O_RDWR);

       or

       newfd = openat(attrdirfd, "attr", O_CREAT|O_RDWR);

       Example 5: Write	to an extended attribute.

       count = write(newfd, buf, length);

       Example 6: Delete an extended attribute.

       error = unlinkat(attrdirfd, "attr");

       Applications intending to access	the interfaces defined here as well as
       the POSIX and X/Open specification-conforming interfaces	should	define
       the  macro _ATFILE_SOURCE to be 1 and set whichever feature test	macros
       are appropriate to obtain the desired environment. See standards(5).

   Extended Archive Formats
       As noted	above in the description of command utilities modified to pro-
       vide  support  for  extended attributes,	the archive formats for	tar(1)
       and cpio(1) have	been extended to provide  support  for	archiving  ex-
       tended  attributes. This	section	describes the specifics	of the archive
       format extensions.

   Extended tar	format
       The tar archive is made up  of  a  series  of  512  byte	 blocks.  Each
       archived	 file  is  represented by a header block and zero or more data
       blocks containing the file contents. The	header block is	structured  as
       shown in	the following table.

       Field Name	    Length (in Octets)	  Description
       Name		    100			  File name string
       Mode		    8			  12 file mode bits
       Uid		    8			  User ID of file owner
       Gid		    8			  Group	ID of file owner
       Size		    12			  Size of file
       Mtime		    12			  File modification time
       Chksum		    8			  File contents	checksum
       Typeflag		    1			  File type flag
       Linkname		    100			  Link target name if file linked
       Magic		    6			  "ustar"
       Version		    2			  "00"
       Uname		    32			  User name of file owner
       Gname		    32			  Group	name of	file owner
       Devmajor		    8			  Major	device ID if special file
       Devminor		    8			  Minor	device ID if special file
       Prefix		    155			  Path prefix string for file

       The  extended  attribute	 project  extends  the	above header format by
       defining	a new header type (for the Typeflag field). The	 type  'E'  is
       defined	to  be	used for all extended attribute	files. Attribute files
       are stored in the tar archive as	 a  sequence  of  two  <header	,data>
       pairs.  The  first  file	contains the data necessary to locate and name
       the extended attribute in the file system. The second file contains the
       actual  attribute  file	data.	Both files use an 'E' type header. The
       prefix and name fields  in  extended  attribute	headers	 are  ignored,
       though  they  should  be	 set  to  meaningful values for	the benefit of
       archivers that do not process these headers. Solaris archivers set  the
       prefix field to "/dev/null" to prevent archivers	that do	not understand
       the type	'E' header from	trying to restore extended attribute files  in
       inappropriate places.

   Extended cpio format
       The  cpio  archive format is octet-oriented rather than block-oriented.
       Each file entry in the archive includes a  header  that	describes  the
       file,  followed by the file name, followed by the contents of the file.
       These data are arranged as described in the following table.

       Field Name	    Length (in Octets)	  Description
       c_magic		    6			  70707
       c_dev		    6			  First	half of	unique file ID
       c_ino		    6			  Second half of unique	file ID
       c_mode		    6			  File mode bits
       c_uid		    6			  User ID of file owner
       c_gid		    6			  Group	ID of file owner
       c_nlink		    6			  Number of links referencing file
       c_rdev		    6			  Information for special files
       c_mtime		    11			  Modification time of file

       c_namesize	    6			  Length of file pathname
       c_filesize	    11			  Length of file content
       c_name		    c_namesize		  File pathname
       c_filedata	    c_filesize		  File content

       The basic archive file  structure  is  not  changed  for	 extended  at-
       tributes.  The  file type bits stored in	the c_mode field for an	attri-
       bute file are set to 0xB000. As with the	tar archive  format,  extended
       attributes are stored in	cpio archives as two consecutive file entries.
       The first file describes	the location/name for the extended  attribute.
       The  second file	contains the actual attribute file content. The	c_name
       field in	extended attribute headers is ignored, though it should	be set
       to  a meaningful	value for the benefit of archivers that	do not process
       these headers.  Solaris archivers start the pathname with  "/dev/null/"
       to  prevent  archivers  that do not understand the type 'E' header from
       trying to restore extended attribute files in inappropriate places.

   Attribute identification data format
       Both the	tar and	cpio archive formats can contain the special files de-
       scribed	above,	always paired with the extended	attribute data record,
       for identifying the precise location of the extended attribute.	 These
       special	data  files  are  necessary  because there is no simple	naming
       mechanism for extended attribute	files.	Extended  attributes  are  not
       visible	in  the	 file  system  name space. The extended	attribute name
       space must be "tunneled into" using the openat()	function.  The	attri-
       bute  identification  data must support not only	the flat naming	struc-
       ture for	extended attributes, but also the possibility of future	exten-
       sions  allowing	for  attribute directory hierarchies and recursive at-
       tributes. The data file is therefore composed of	a sequence of records.
       It  begins with a fixed length header describing	 the content. The fol-
       lowing table describes the format of this data file.

       Field Name	   Length (in Octets)	Description
       h_version	   7			Name file version
       h_size		   10			Length of data file
       h_component_len	   10			Total length of	all path segments
       h_link_comp_len	   10			Total length of	all link segments
       path		   h_component_len	Complex	path
       link_path	   h_link_comp_len	Complex	link path

       As demonstrated above, the header is followed by	 a  record  describing
       the  "path" to the attribute file. This path is composed	of two or more
       path segments separated by a null character. Each segment  describes  a
       path rooted at the hidden extended attribute directory of the leaf file
       of the previous segment,	making it possible to name attributes  on  at-
       tributes.  The first segment is always the path to the parent file that
       roots the entire	sequence in the	normal name space. The following table
       describes the format of each segment.

       Field Name	  Length (in Octets)   Description
       h_namesz		  7		       Length of segment path
       h_typeflag	  1		       Actual file type	of attribute file
       h_names		  h_namesz	       Parent path + segment path

       If  the	attribute  file	 is linked to another file, the	path record is
       followed	by a second record describing the location of the  referencing
       file.   The  structure  of  this	 record	is identical to	the record de-
       scribed above.

SEE ALSO
       cp(1), cpio(1), find(1),	ls(1), mv(1), pax(1), runat(1),	tar(1),	du(1),
       fsck(1M),  chown(2), link(2), open(2), pathconf(2), rename(2), stat(2),
       unlink(2), utimes(2), attropen(3C), standards(5)

SunOS 5.10			  1 Aug	2001			     fsattr(5)

NAME | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=fsattr&sektion=5&manpath=SunOS+5.10>

home | help