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.

AUTHOR

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

Richard Dawe, <richdawe@cpan.org>

COPYRIGHT AND LICENSE

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.

To install File::ExtAttr, copy and paste the appropriate command in to your terminal.

cpanm

cpanm File::ExtAttr

CPAN shell

perl -MCPAN -e shell
install File::ExtAttr

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)