File::ExtAttr(3pm)

1File::ExtAttr(3)      User Contributed Perl Documentation     File::ExtAttr(3)
2
3
4

NAME

6       File::ExtAttr - Perl extension for accessing extended attributes of
7       files
8

SYNOPSIS

10         use File::ExtAttr ':all';
11         use IO::File;
12
13         # Manipulate the extended attributes of files.
14         setfattr('foo.txt', 'colour', 'red') ⎪⎪ die;
15         my $colour = getfattr('bar.txt', 'colour');
16         if (defined($colour))
17         {
18             print $colour;
19             delfattr('bar.txt', 'colour');
20         }
21
22         # Manipulate the extended attributes of a file via a file handle.
23         my $fh = new IO::File('<foo.txt') ⎪⎪ die;
24         setfattr($fh, 'colour', 'red') ⎪⎪ die;
25
26         $fh = new IO::File('<bar.txt') ⎪⎪ die;
27         $colour = getfattr($fh, 'colour');
28         if (defined($colour))
29         {
30             print $colour;
31             delfattr($fh, 'colour');
32         }
33
34         # List attributes in the default namespace.
35         print "Attributes of bar.txt:\n";
36         foreach (listfattr($fh))
37         {
38           print "\t$_\n";
39         }
40
41         # Examine attributes in a namespace-aware manner.
42         my @namespaces = listfattrns($fh);
43
44         foreach my $ns (@namespaces)
45         {
46           print "Attributes in namespace '$ns': ";
47           my @attrs = listfattr($fh, { namespace => $ns });
48           print join(',', @attrs)."\n";
49         }
50

DESCRIPTION

52       File::ExtAttr is a Perl module providing access to the extended
53       attributes of files.
54
55       Extended attributes are metadata associated with a file.  Examples are
56       access control lists (ACLs) and other security parameters.  But users
57       can add their own key=value pairs.
58
59       Extended attributes may not be supported by your operating system.
60       This module is aimed at Linux, Unix or Unix-like operating systems
61       (e.g.: Mac OS X, FreeBSD, NetBSD, OpenBSD).
62
63       Extended attributes may also not be supported by your filesystem or
64       require special options to be enabled for a particular filesystem.
65       E.g.:
66
67         mount -o user_xattr /dev/hda1 /some/path
68
69       Namespaces
70
71       Some implementations of extended attributes support namespacing.  In
72       those implementations, the attribute is referred to by namespace and
73       attribute name.
74
75       Linux
76           The primary namespaces are "user" for user programs; "security",
77           "system" and "trusted" for file security/access-control.  See
78           <http://www.die.net/doc/linux/man/man5/attr.5.html> for more
79           details.
80
81           Namespaces on Linux are described by a string, but only certain
82           values are supported by filesystems. In general "user", "security",
83           "system" and "trusted" are supported, by others may be supported --
84           e.g.: "os2" on JFS. File::Extattr will be able to access any of
85           these.
86
87       FreeBSD, NetBSD, OpenBSD
88           *BSD have two namespaces: "user" and "system".
89
90           Namespaces on *BSD are described by an integer. File::ExtAttr will
91           only be able to access attributes in "user" and "system".
92
93       Mac OS X
94           OS X has no support for namespaces.
95
96       Solaris
97           Solaris has no support for namespaces.
98
99       Flags
100
101       The functions take a hash reference as their final parameter, which can
102       specify flags to modify the behaviour of the functions.  The flags spe‐
103       cific to a function are documented in the function's description.
104
105       All functions support a "namespace" flag. E.g.:
106
107         use File::ExtAttr ':all';
108         use IO::File;
109
110         # Manipulate the extended attributes of files.
111         setfattr('foo.txt', 'colour', 'red') ⎪⎪ die;
112         my $colour = getfattr('bar.txt', 'colour', { namespace => 'user');
113
114       If no namespace is specified, the default namespace will be used.  On
115       Linux and *BSD the default namespace will be "user".
116

METHODS

118       getfattr([$filename ⎪ $filehandle], $attrname, [\%flags])
119           Return the value of the attribute named $attrname for the file
120           named $filename or referenced by the open filehandle $filehandle
121           (which should be an IO::Handle or subclass thereof).
122
123           If no attribute is found, returns "undef". Otherwise gives a warn‐
124           ing.
125
126       setfattr([$filename ⎪ $filehandle], $attrname, $attrval, [\%flags])
127           Set the attribute named $attrname with the value $attrval for the
128           file named $filename or referenced by the open filehandle $filehan‐
129           dle (which should be an IO::Handle or subclass thereof).
130
131           %flags allows control of whether the attribute should be created or
132           should replace an existing attribute\'s value. If the key "create"
133           is true, setfattr will fail if the attribute already exists. If the
134           key "replace" is true, setfattr will fail if the attribute does not
135           already exist. If neither is specified, then the attribute will be
136           created (if necessary) or silently replaced.
137
138           If the attribute could not be set, a warning is issued.
139
140           Note that "create" cannot be implemented in a race-free manner on
141           *BSD.  If your code relies on the "create" behaviour, it may be
142           insecure on *BSD.
143
144       delfattr([$filename ⎪ $filehandle], $attrname, [\%flags])
145           Delete the attribute named $attrname for the file named $filename
146           or referenced by the open filehandle $filehandle (which should be
147           an IO::Handle or subclass thereof).
148
149           Returns true on success, otherwise false and a warning is issued.
150
151       listfattr([$filename ⎪ $filehandle], [\%flags])
152           Return an array of the attributes on the file named $filename or
153           referenced by the open filehandle $filehandle (which should be an
154           IO::Handle or subclass thereof).
155
156           Returns undef on failure and $! will be set.
157
158       listfattrns([$filename ⎪ $filehandle], [\%flags])
159           Return an array containing the namespaces of attributes on the file
160           named $filename or referenced by the open filehandle $filehandle
161           (which should be an IO::Handle or subclass thereof).
162
163           Returns undef on failure and $! will be set.
164

EXPORT

166       None by default.
167
168       You can request that "getfattr", "setfattr", "delfattr" and "listfattr"
169       be exported using the tag ":all".
170
171       Exportable constants
172
173       None
174

AUTHOR

225       Kevin M. Goess, <kgoess@ensenda.com>
226
227       Richard Dawe, <rich@phekda.gotadsl.co.uk>
228

COPYRIGHT AND LICENSE

230       Copyright (C) 2005 by Kevin M. Goess
231
232       Copyright (C) 2005, 2006, 2007 by Richard Dawe
233
234       This library is free software; you can redistribute it and/or modify it
235       under the same terms as Perl itself, either Perl version 5.8.5 or, at
236       your option, any later version of Perl 5 you may have available.
237
238
239
240perl v5.8.8                       2007-04-06                  File::ExtAttr(3)