Provided by: libfile-extattr-perl_1.09-4_amd64 bug

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.