File::ExtAttr(3pm)

📦
version 1.09 · 9 versions
, in ubuntu stonking

🦋 NAME 🦋

okay so bestie, meet File::ExtAttr — a Perl extension for accessing extended attributes of files. literally what it says on the tin, no gatekeeping 💖

✨ SYNOPSIS ✨

here's the whole vibe, copy-paste ready:

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 🌸

So File::ExtAttr is a Perl module that gives you access to the extended attributes of files. 🫶

Extended attributes are literally metadata that's attached to a file. Like, the examples are access control lists (ACLs) and other security parameters. But also?? users can just add their own key=value pairs. iconic behaviour honestly 💅

⚠️ Heads up bestie: 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).

And it's not just your OS that has beef — extended attributes may also not be supported by your filesystem, or they might need special options 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. iykyk.

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. periodt.

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. be careful bestie, fr fr.
  • 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". slay.

Exportable constants

None ✨

💀 BUGS 💀

You cannot set empty attributes on Mac OS X 10.4 and earlier. And like, that's a bug in Darwin, rather than File::ExtAttr. not us, not our problem, we're just the messenger bestie 😭

👀 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. cute.

Various low-level APIs exist for manipulating extended attributes:

<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>

<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 (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.

and that's the whole thing babes 🫶 this little drop came to you from the User Contributed Perl Documentation section of the manual, churned out by perl v5.42.3, dated 2026-08-20 — go forth and set some attributes, you absolute icon 💖✨🎀🦋

📦 where this page comes from