.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "File::ExtAttr 3pm"
.TH File::ExtAttr 3pm "2020-11-08" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
File::ExtAttr \- Perl extension for accessing extended attributes of files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use File::ExtAttr \*(Aq:all\*(Aq;
\&  use IO::File;
\&  
\&  # Manipulate the extended attributes of files.
\&  setfattr(\*(Aqfoo.txt\*(Aq, \*(Aqcolour\*(Aq, \*(Aqred\*(Aq) || die;
\&  my $colour = getfattr(\*(Aqbar.txt\*(Aq, \*(Aqcolour\*(Aq);
\&  if (defined($colour))
\&  {
\&      print $colour;
\&      delfattr(\*(Aqbar.txt\*(Aq, \*(Aqcolour\*(Aq);
\&  }
\&  
\&  # Manipulate the extended attributes of a file via a file handle.
\&  my $fh = new IO::File(\*(Aq<foo.txt\*(Aq) || die;
\&  setfattr($fh, \*(Aqcolour\*(Aq, \*(Aqred\*(Aq) || die;
\&  
\&  $fh = new IO::File(\*(Aq<bar.txt\*(Aq) || die;
\&  $colour = getfattr($fh, \*(Aqcolour\*(Aq);
\&  if (defined($colour))
\&  {
\&      print $colour;
\&      delfattr($fh, \*(Aqcolour\*(Aq);
\&  }
\&
\&  # List attributes in the default namespace.
\&  print "Attributes of bar.txt:\en";
\&  foreach (listfattr($fh))
\&  {
\&    print "\et$_\en";
\&  }
\&
\&  # Examine attributes in a namespace\-aware manner.
\&  my @namespaces = listfattrns($fh);
\&
\&  foreach my $ns (@namespaces)
\&  {
\&    print "Attributes in namespace \*(Aq$ns\*(Aq: ";
\&    my @attrs = listfattr($fh, { namespace => $ns });
\&    print join(\*(Aq,\*(Aq, @attrs)."\en";
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
File::ExtAttr is a Perl module providing access to the extended attributes
of files.
.PP
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.
.PP
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 \s-1OS X,\s0 FreeBSD, NetBSD, Solaris).
.PP
Extended attributes may also not be supported by your filesystem
or require special options to be enabled for a particular filesystem.
E.g.:
.PP
.Vb 1
\&  mount \-o user_xattr /dev/hda1 /some/path
.Ve
.SS "Supported OSes"
.IX Subsection "Supported OSes"
.IP "Linux" 4
.IX Item "Linux"
.PD 0
.IP "Mac \s-1OS X\s0" 4
.IX Item "Mac OS X"
.IP "FreeBSD 5.0 and later" 4
.IX Item "FreeBSD 5.0 and later"
.IP "NetBSD 4.0 and later" 4
.IX Item "NetBSD 4.0 and later"
.IP "Solaris 10 and later" 4
.IX Item "Solaris 10 and later"
.PD
.SS "Unsupported OSes"
.IX Subsection "Unsupported OSes"
.IP "OpenBSD" 4
.IX Item "OpenBSD"
.SS "Namespaces"
.IX Subsection "Namespaces"
Some implementations of extended attributes support namespacing.
In those implementations, the attribute is referred to by namespace
and attribute name.
.IP "Linux" 4
.IX Item "Linux"
The primary namespaces are \f(CW\*(C`user\*(C'\fR for user programs;
\&\f(CW\*(C`security\*(C'\fR, \f(CW\*(C`system\*(C'\fR and \f(CW\*(C`trusted\*(C'\fR for file security/access\-control.
See <http://www.die.net/doc/linux/man/man5/attr.5.html>
for more details.
.Sp
Namespaces on Linux are described by a string, but only certain values
are supported by filesystems. In general \f(CW\*(C`user\*(C'\fR, \f(CW\*(C`security\*(C'\fR, \f(CW\*(C`system\*(C'\fR
and \f(CW\*(C`trusted\*(C'\fR are supported, by others may be supported \*(--
e.g.: \f(CW\*(C`os2\*(C'\fR on \s-1JFS.\s0 File::Extattr will be able to access any of these.
.IP "FreeBSD, NetBSD" 4
.IX Item "FreeBSD, NetBSD"
*BSD have two namespaces: \f(CW\*(C`user\*(C'\fR and \f(CW\*(C`system\*(C'\fR.
.Sp
Namespaces on *BSD are described by an integer. File::ExtAttr will only
be able to access attributes in \f(CW\*(C`user\*(C'\fR and \f(CW\*(C`system\*(C'\fR.
.IP "Mac \s-1OS X\s0" 4
.IX Item "Mac OS X"
\&\s-1OS X\s0 has no support for namespaces.
.IP "Solaris" 4
.IX Item "Solaris"
Solaris has no support for namespaces.
.SS "Flags"
.IX Subsection "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.
.PP
All functions support a \f(CW\*(C`namespace\*(C'\fR flag. E.g.:
.PP
.Vb 2
\&  use File::ExtAttr \*(Aq:all\*(Aq;
\&  use IO::File;
\&  
\&  # Manipulate the extended attributes of files.
\&  setfattr(\*(Aqfoo.txt\*(Aq, \*(Aqcolour\*(Aq, \*(Aqred\*(Aq) || die;
\&  my $colour = getfattr(\*(Aqbar.txt\*(Aq, \*(Aqcolour\*(Aq, { namespace => \*(Aquser\*(Aq);
.Ve
.PP
If no namespace is specified, the default namespace will be used.
On Linux and *BSD the default namespace will be \f(CW\*(C`user\*(C'\fR.
.SH "METHODS"
.IX Header "METHODS"
.ie n .IP "getfattr([$filename | $filehandle], $attrname, [\e%flags])" 4
.el .IP "getfattr([$filename | \f(CW$filehandle\fR], \f(CW$attrname\fR, [\e%flags])" 4
.IX Item "getfattr([$filename | $filehandle], $attrname, [%flags])"
Return the value of the attribute named \f(CW$attrname\fR
for the file named \f(CW$filename\fR or referenced by the open filehandle
\&\f(CW$filehandle\fR (which should be an IO::Handle or subclass thereof).
.Sp
If no attribute is found, returns \f(CW\*(C`undef\*(C'\fR. Otherwise gives a warning.
.ie n .IP "setfattr([$filename | $filehandle], $attrname, $attrval, [\e%flags])" 4
.el .IP "setfattr([$filename | \f(CW$filehandle\fR], \f(CW$attrname\fR, \f(CW$attrval\fR, [\e%flags])" 4
.IX Item "setfattr([$filename | $filehandle], $attrname, $attrval, [%flags])"
Set the attribute named \f(CW$attrname\fR with the value \f(CW$attrval\fR
for the file named \f(CW$filename\fR or referenced by the open filehandle
\&\f(CW$filehandle\fR (which should be an IO::Handle or subclass thereof).
.Sp
\&\f(CW%flags\fR allows control of whether the attribute should be created
or should replace an existing attribute's value. If the key \f(CW\*(C`create\*(C'\fR
is true, setfattr will fail if the attribute already exists. If the key
\&\f(CW\*(C`replace\*(C'\fR 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.
.Sp
If the attribute could not be set, a warning is issued.
.Sp
Note that \f(CW\*(C`create\*(C'\fR cannot be implemented in a race-free manner on *BSD.
If your code relies on the \f(CW\*(C`create\*(C'\fR behaviour, it may be insecure on *BSD.
.ie n .IP "delfattr([$filename | $filehandle], $attrname, [\e%flags])" 4
.el .IP "delfattr([$filename | \f(CW$filehandle\fR], \f(CW$attrname\fR, [\e%flags])" 4
.IX Item "delfattr([$filename | $filehandle], $attrname, [%flags])"
Delete the attribute named \f(CW$attrname\fR for the file named \f(CW$filename\fR
or referenced by the open filehandle \f(CW$filehandle\fR
(which should be an IO::Handle or subclass thereof).
.Sp
Returns true on success, otherwise false and a warning is issued.
.ie n .IP "listfattr([$filename | $filehandle], [\e%flags])" 4
.el .IP "listfattr([$filename | \f(CW$filehandle\fR], [\e%flags])" 4
.IX Item "listfattr([$filename | $filehandle], [%flags])"
Return an array of the attributes on the file named \f(CW$filename\fR
or referenced by the open filehandle \f(CW$filehandle\fR (which should be
an IO::Handle or subclass thereof).
.Sp
Returns undef on failure and $! will be set.
.ie n .IP "listfattrns([$filename | $filehandle], [\e%flags])" 4
.el .IP "listfattrns([$filename | \f(CW$filehandle\fR], [\e%flags])" 4
.IX Item "listfattrns([$filename | $filehandle], [%flags])"
Return an array containing the namespaces of attributes on the file named
\&\f(CW$filename\fR or referenced by the open filehandle \f(CW$filehandle\fR
(which should be an IO::Handle or subclass thereof).
.Sp
Returns undef on failure and $! will be set.
.SH "EXPORT"
.IX Header "EXPORT"
None by default.
.PP
You can request that \f(CW\*(C`getfattr\*(C'\fR, \f(CW\*(C`setfattr\*(C'\fR, \f(CW\*(C`delfattr\*(C'\fR
and \f(CW\*(C`listfattr\*(C'\fR be exported using the tag \*(L":all\*(R".
.SS "Exportable constants"
.IX Subsection "Exportable constants"
None
.SH "BUGS"
.IX Header "BUGS"
You cannot set empty attributes on Mac \s-1OS X 10.4\s0 and earlier.
This is a bug in Darwin, rather than File::ExtAttr.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The latest version of this software should be available from its
home page: <http://sourceforge.net/projects/file\-extattr/>
.PP
OS2::ExtAttr provides access to extended attributes on \s-1OS/2.\s0
.PP
Eiciel, <http://rofi.pinchito.com/eiciel/>, is an access control list (\s-1ACL\s0)
editor for \s-1GNOME\s0; the ACLs are stored in extended attributes.
.PP
Various low-level APIs exist for manipulating extended attributes:
.IP "Linux" 4
.IX Item "Linux"
\&\fBgetattr\fR\|(2), \fBattr\fR\|(5)
.Sp
<http://www.die.net/doc/linux/man/man2/getxattr.2.html>
.Sp
<http://www.die.net/doc/linux/man/man5/attr.5.html>
.IP "OpenBSD" 4
.IX Item "OpenBSD"
OpenBSD 3.7 supported extended attributes, although support was never
built into the default \s-1GENERIC\s0 kernel. Its support was documented
in the \f(CW\*(C`extattr\*(C'\fR man page:
.Sp
<http://www.openbsd.org/cgi\-bin/man.cgi?query=extattr_get_file&apropos=0&sektion=0&manpath=OpenBSD+Current&arch=i386&format=html>
.Sp
Support was removed in OpenBSD 3.8 \*(-- see the \s-1CVS\s0 history
for the include file \f(CW\*(C`sys/extattr.h\*(C'\fR.
.Sp
<http://www.openbsd.org/cgi\-bin/cvsweb/src/sys/sys/Attic/extattr.h>
.IP "FreeBSD" 4
.IX Item "FreeBSD"
FreeBSD >= 5.0 supports extended attributes.
.Sp
\&\fBextattr\fR\|(2)
.Sp
<http://www.freebsd.org/cgi/man.cgi?query=extattr&sektion=2&apropos=0&manpath=FreeBSD+6.0\-RELEASE+and+Ports>
.IP "NetBSD" 4
.IX Item "NetBSD"
NetBSD >= 3.0 supports extended attributes, but you'll need to use
NetBSD >= 4.0 to get \s-1UFS\s0 filesystem support for them.
.Sp
<http://netbsd.gw.com/cgi\-bin/man\-cgi?extattr_get_file+2+NetBSD\-current>
.Sp
<http://www.netbsd.org/Changes/changes\-4.0.html#ufs>
.IP "Mac \s-1OS X\s0" 4
.IX Item "Mac OS X"
\&\fBgetxattr\fR\|(2)
.Sp
<http://developer.apple.com/documentation/Darwin/Reference/ManPages/man2/getxattr.2.html>
.Sp
<http://arstechnica.com/reviews/os/macosx\-10.4.ars/7>
.IP "Solaris" 4
.IX Item "Solaris"
attropen(3C), \fBfsattr\fR\|(5)
.Sp
<http://docsun.cites.uiuc.edu/sun_docs/C/solaris_9/SUNWaman/hman3c/attropen.3c.html>
.Sp
<http://docsun.cites.uiuc.edu/sun_docs/C/solaris_9/SUNWaman/hman5/fsattr.5.html>
.Sp
Solaris also has extensible system attributes, which are used
by Solaris's \s-1CIFS\s0 support on \s-1ZFS,\s0 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 \s-1PSARC 2007/315\s0 for more details:
.Sp
<http://opensolaris.org/os/community/arc/caselog/2007/315/spec\-final\-txt/>
.SH "AUTHOR"
.IX Header "AUTHOR"
Kevin M. Goess, <kgoess@ensenda.com>
.PP
Richard Dawe, <richdawe@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2005 by Kevin M. Goess
.PP
Copyright (C) 2005, 2006, 2007, 2008 by Richard Dawe
.PP
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.