File::ExtAttr(3) User Contributed Perl Documentation File::ExtAttr(3)NAMEFile::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";
}
DESCRIPTIONFile::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/
<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
<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
<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
<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://netbsd.gw.com/cgi-bin/man-cgi?extattr_get_file+2+NetBSD-
current>
http://www.netbsd.org/Changes/changes-4.0.html#ufs
<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
<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/
<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.14.1 2009-03-05 File::ExtAttr(3)
