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

FreeBSD Manual Pages

  
 
  

home | help
File::ExtAttr(3)      User Contributed Perl Documentation     File::ExtAttr(3)

NAME
       File::ExtAttr - Perl extension for accessing extended attributes	of
       files

SYNOPSIS
	 use File::ExtAttr ':all';
	 use IO::File;

	 # Manipulate the extended attributes of files.
	 setfattr('foo.txt', 'colour', 'red') || die;
	 my $colour = getfattr('bar.txt', 'colour');
	 if (defined($colour))
	 {
	     print $colour;
	     delfattr('bar.txt', 'colour');
	 }

	 # Manipulate the extended attributes of a file	via a file handle.
	 my $fh	= new IO::File('<foo.txt') || die;
	 setfattr($fh, 'colour', 'red')	|| die;

	 $fh = new IO::File('<bar.txt')	|| die;
	 $colour = getfattr($fh, 'colour');
	 if (defined($colour))
	 {
	     print $colour;
	     delfattr($fh, 'colour');
	 }

	 # List	attributes in the default namespace.
	 print "Attributes of bar.txt:\n";
	 foreach (listfattr($fh))
	 {
	   print "\t$_\n";
	 }

	 # Examine attributes in a namespace-aware manner.
	 my @namespaces	= listfattrns($fh);

	 foreach my $ns	(@namespaces)
	 {
	   print "Attributes in	namespace '$ns': ";
	   my @attrs = listfattr($fh, {	namespace => $ns });
	   print join(',', @attrs)."\n";
	 }

DESCRIPTION
       File::ExtAttr is	a Perl module providing	access to the extended
       attributes of files.

       Extended	attributes are metadata	associated with	a file.	 Examples are
       access control lists (ACLs) and other security parameters.  But users
       can add their own key=value pairs.

       Extended	attributes may not be supported	by your	operating system.
       This module is aimed at Linux, Unix or Unix-like	operating systems
       (e.g.: Mac OS X,	FreeBSD, NetBSD, Solaris).

       Extended	attributes may also not	be supported by	your filesystem	or
       require special options to be enabled for a particular filesystem.
       E.g.:

	 mount -o user_xattr /dev/hda1 /some/path

   Supported OSes
       Linux
       Mac OS X
       FreeBSD 5.0 and later
       NetBSD 4.0 and later
       Solaris 10 and later

   Unsupported OSes
       OpenBSD

   Namespaces
       Some implementations of extended	attributes support namespacing.	 In
       those implementations, the attribute is referred	to by namespace	and
       attribute name.

       Linux
	   The primary namespaces are "user" for user programs;	"security",
	   "system" and	"trusted" for file security/access-control.  See
	   <http://www.die.net/doc/linux/man/man5/attr.5.html> for more
	   details.

	   Namespaces on Linux are described by	a string, but only certain
	   values are supported	by filesystems.	In general "user", "security",
	   "system" and	"trusted" are supported, by others may be supported --
	   e.g.: "os2" on JFS. File::Extattr will be able to access any	of
	   these.

       FreeBSD,	NetBSD
	   *BSD	have two namespaces: "user" and	"system".

	   Namespaces on *BSD are described by an integer. File::ExtAttr will
	   only	be able	to access attributes in	"user" and "system".

       Mac OS X
	   OS X	has no support for namespaces.

       Solaris
	   Solaris has no support for namespaces.

   Flags
       The functions take a hash reference as their final parameter, which can
       specify flags to	modify the behaviour of	the functions.	The flags
       specific	to a function are documented in	the function's description.

       All functions support a "namespace" flag. E.g.:

	 use File::ExtAttr ':all';
	 use IO::File;

	 # Manipulate the extended attributes of files.
	 setfattr('foo.txt', 'colour', 'red') || die;
	 my $colour = getfattr('bar.txt', 'colour', { namespace	=> 'user');

       If no namespace is specified, the default namespace will	be used.  On
       Linux and *BSD the default namespace will be "user".

METHODS
       getfattr([$filename | $filehandle], $attrname, [\%flags])
	   Return the value of the attribute named $attrname for the file
	   named $filename or referenced by the	open filehandle	$filehandle
	   (which should be an IO::Handle or subclass thereof).

	   If no attribute is found, returns "undef". Otherwise	gives a
	   warning.

       setfattr([$filename | $filehandle], $attrname, $attrval,	[\%flags])
	   Set the attribute named $attrname with the value $attrval for the
	   file	named $filename	or referenced by the open filehandle
	   $filehandle (which should be	an IO::Handle or subclass thereof).

	   %flags allows control of whether the	attribute should be created or
	   should replace an existing attribute's value. If the	key "create"
	   is true, setfattr will fail if the attribute	already	exists.	If the
	   key "replace" is true, setfattr will	fail if	the attribute does not
	   already exist. If neither is	specified, then	the attribute will be
	   created (if necessary) or silently replaced.

	   If the attribute could not be set, a	warning	is issued.

	   Note	that "create" cannot be	implemented in a race-free manner on
	   *BSD.  If your code relies on the "create" behaviour, it may	be
	   insecure on *BSD.

       delfattr([$filename | $filehandle], $attrname, [\%flags])
	   Delete the attribute	named $attrname	for the	file named $filename
	   or referenced by the	open filehandle	$filehandle (which should be
	   an IO::Handle or subclass thereof).

	   Returns true	on success, otherwise false and	a warning is issued.

       listfattr([$filename | $filehandle], [\%flags])
	   Return an array of the attributes on	the file named $filename or
	   referenced by the open filehandle $filehandle (which	should be an
	   IO::Handle or subclass thereof).

	   Returns undef on failure and	$! will	be set.

       listfattrns([$filename |	$filehandle], [\%flags])
	   Return an array containing the namespaces of	attributes on the file
	   named $filename or referenced by the	open filehandle	$filehandle
	   (which should be an IO::Handle or subclass thereof).

	   Returns undef on failure and	$! will	be set.

EXPORT
       None by default.

       You can request that "getfattr",	"setfattr", "delfattr" and "listfattr"
       be exported using the tag ":all".

   Exportable constants
       None

BUGS
       You cannot set empty attributes on Mac OS X 10.4	and earlier.  This is
       a bug in	Darwin,	rather than File::ExtAttr.

SEE ALSO
       The latest version of this software should be available from its	home
       page: <http://sourceforge.net/projects/file-extattr/>

       OS2::ExtAttr provides access to extended	attributes on OS/2.

       Eiciel, <http://rofi.pinchito.com/eiciel/>, is an access	control	list
       (ACL) editor for	GNOME; the ACLs	are stored in extended attributes.

       Various low-level APIs exist for	manipulating extended attributes:

       Linux
	   getattr(2), attr(5)

	   <http://www.die.net/doc/linux/man/man2/getxattr.2.html>

	   <http://www.die.net/doc/linux/man/man5/attr.5.html>

       OpenBSD
	   OpenBSD 3.7 supported extended attributes, although support was
	   never built into the	default	GENERIC	kernel.	Its support was
	   documented in the "extattr" man page:

	   <http://www.openbsd.org/cgi-bin/man.cgi?query=extattr_get_file&apropos=0&sektion=0&manpath=OpenBSD+Current&arch=i386&format=html>

	   Support was removed in OpenBSD 3.8 -- see the CVS history for the
	   include file	"sys/extattr.h".

	   <http://www.openbsd.org/cgi-bin/cvsweb/src/sys/sys/Attic/extattr.h>

       FreeBSD
	   FreeBSD >= 5.0 supports extended attributes.

	   extattr(2)

	   <http://www.freebsd.org/cgi/man.cgi?query=extattr&sektion=2&apropos=0&manpath=FreeBSD+6.0-RELEASE+and+Ports>

       NetBSD
	   NetBSD >= 3.0 supports extended attributes, but you'll need to use
	   NetBSD >= 4.0 to get	UFS filesystem support for them.

	   <http://netbsd.gw.com/cgi-bin/man-cgi?extattr_get_file+2+NetBSD-current>

	   <http://www.netbsd.org/Changes/changes-4.0.html#ufs>

       Mac OS X
	   getxattr(2)

	   <http://developer.apple.com/documentation/Darwin/Reference/ManPages/man2/getxattr.2.html>

	   <http://arstechnica.com/reviews/os/macosx-10.4.ars/7>

       Solaris
	   attropen(3C), fsattr(5)

	   <http://docsun.cites.uiuc.edu/sun_docs/C/solaris_9/SUNWaman/hman3c/attropen.3c.html>

	   <http://docsun.cites.uiuc.edu/sun_docs/C/solaris_9/SUNWaman/hman5/fsattr.5.html>

	   Solaris also	has extensible system attributes, which	are used by
	   Solaris's CIFS support on ZFS, and have a confusingly similar name
	   to extended file attributes.	These system attributes	are stored in
	   extended file attributes called SUNWattr_ro and SUNWattr_rw.	 See
	   PSARC 2007/315 for more details:

	   <http://opensolaris.org/os/community/arc/caselog/2007/315/spec-final-txt/>

AUTHOR
       Kevin M.	Goess, <kgoess@ensenda.com>

       Richard Dawe, <richdawe@cpan.org>

COPYRIGHT AND LICENSE
       Copyright (C) 2005 by Kevin M. Goess

       Copyright (C) 2005, 2006, 2007, 2008 by Richard Dawe

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself, either Perl	version	5.8.5 or, at
       your option, any	later version of Perl 5	you may	have available.

perl v5.32.0			  2009-03-05		      File::ExtAttr(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | EXPORT | BUGS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=File::ExtAttr&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help