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, Solaris).
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   Supported OSes
70       Linux
71       Mac OS X
72       FreeBSD 5.0 and later
73       NetBSD 4.0 and later
74       Solaris 10 and later
75
76   Unsupported OSes
77       OpenBSD
78
79   Namespaces
80       Some implementations of extended attributes support namespacing.  In
81       those implementations, the attribute is referred to by namespace and
82       attribute name.
83
84       Linux
85           The primary namespaces are "user" for user programs; "security",
86           "system" and "trusted" for file security/access-control.  See
87           <http://www.die.net/doc/linux/man/man5/attr.5.html> for more
88           details.
89
90           Namespaces on Linux are described by a string, but only certain
91           values are supported by filesystems. In general "user", "security",
92           "system" and "trusted" are supported, by others may be supported --
93           e.g.: "os2" on JFS. File::Extattr will be able to access any of
94           these.
95
96       FreeBSD, NetBSD
97           *BSD have two namespaces: "user" and "system".
98
99           Namespaces on *BSD are described by an integer. File::ExtAttr will
100           only be able to access attributes in "user" and "system".
101
102       Mac OS X
103           OS X has no support for namespaces.
104
105       Solaris
106           Solaris has no support for namespaces.
107
108   Flags
109       The functions take a hash reference as their final parameter, which can
110       specify flags to modify the behaviour of the functions.  The flags
111       specific to a function are documented in the function's description.
112
113       All functions support a "namespace" flag. E.g.:
114
115         use File::ExtAttr ':all';
116         use IO::File;
117
118         # Manipulate the extended attributes of files.
119         setfattr('foo.txt', 'colour', 'red') || die;
120         my $colour = getfattr('bar.txt', 'colour', { namespace => 'user');
121
122       If no namespace is specified, the default namespace will be used.  On
123       Linux and *BSD the default namespace will be "user".
124

METHODS

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

EXPORT

174       None by default.
175
176       You can request that "getfattr", "setfattr", "delfattr" and "listfattr"
177       be exported using the tag ":all".
178
179   Exportable constants
180       None
181

BUGS

183       You cannot set empty attributes on Mac OS X 10.4 and earlier.  This is
184       a bug in Darwin, rather than File::ExtAttr.
185

187       The latest version of this software should be available from its home
188       page: http://sourceforge.net/projects/file-extattr/
189       <http://sourceforge.net/projects/file-extattr/>
190
191       OS2::ExtAttr provides access to extended attributes on OS/2.
192
193       Eiciel, <http://rofi.pinchito.com/eiciel/>, is an access control list
194       (ACL) editor for GNOME; the ACLs are stored in extended attributes.
195
196       Various low-level APIs exist for manipulating extended attributes:
197
198       Linux
199           getattr(2), attr(5)
200
201           <http://www.die.net/doc/linux/man/man2/getxattr.2.html>
202
203           <http://www.die.net/doc/linux/man/man5/attr.5.html>
204
205       OpenBSD
206           OpenBSD 3.7 supported extended attributes, although support was
207           never built into the default GENERIC kernel. Its support was
208           documented in the "extattr" man page:
209
210           http://www.openbsd.org/cgi-bin/man.cgi?query=extattr_get_file&apropos=0&sektion=0&manpath=OpenBSD+Current&arch=i386&format=html
211           <http://www.openbsd.org/cgi-
212           bin/man.cgi?query=extattr_get_file&apropos=0&sektion=0&manpath=OpenBSD+Current&arch=i386&format=html>
213
214           Support was removed in OpenBSD 3.8 -- see the CVS history for the
215           include file "sys/extattr.h".
216
217           http://www.openbsd.org/cgi-bin/cvsweb/src/sys/sys/Attic/extattr.h
218           <http://www.openbsd.org/cgi-bin/cvsweb/src/sys/sys/Attic/extattr.h>
219
220       FreeBSD
221           FreeBSD >= 5.0 supports extended attributes.
222
223           extattr(2)
224
225           http://www.freebsd.org/cgi/man.cgi?query=extattr&sektion=2&apropos=0&manpath=FreeBSD+6.0-RELEASE+and+Ports
226           <http://www.freebsd.org/cgi/man.cgi?query=extattr&sektion=2&apropos=0&manpath=FreeBSD+6.0-RELEASE+and+Ports>
227
228       NetBSD
229           NetBSD >= 3.0 supports extended attributes, but you'll need to use
230           NetBSD >= 4.0 to get UFS filesystem support for them.
231
232           http://netbsd.gw.com/cgi-bin/man-cgi?extattr_get_file+2+NetBSD-current
233           <http://netbsd.gw.com/cgi-bin/man-cgi?extattr_get_file+2+NetBSD-
234           current>
235
236           http://www.netbsd.org/Changes/changes-4.0.html#ufs
237           <http://www.netbsd.org/Changes/changes-4.0.html#ufs>
238
239       Mac OS X
240           getxattr(2)
241
242           <http://developer.apple.com/documentation/Darwin/Reference/ManPages/man2/getxattr.2.html>
243
244           http://arstechnica.com/reviews/os/macosx-10.4.ars/7
245           <http://arstechnica.com/reviews/os/macosx-10.4.ars/7>
246
247       Solaris
248           attropen(3C), fsattr(5)
249
250           <http://docsun.cites.uiuc.edu/sun_docs/C/solaris_9/SUNWaman/hman3c/attropen.3c.html>
251
252           <http://docsun.cites.uiuc.edu/sun_docs/C/solaris_9/SUNWaman/hman5/fsattr.5.html>
253
254           Solaris also has extensible system attributes, which are used by
255           Solaris's CIFS support on ZFS, and have a confusingly similar name
256           to extended file attributes. These system attributes are stored in
257           extended file attributes called SUNWattr_ro and SUNWattr_rw.  See
258           PSARC 2007/315 for more details:
259
260           http://opensolaris.org/os/community/arc/caselog/2007/315/spec-final-txt/
261           <http://opensolaris.org/os/community/arc/caselog/2007/315/spec-
262           final-txt/>
263

AUTHOR

265       Kevin M. Goess, <kgoess@ensenda.com>
266
267       Richard Dawe, <richdawe@cpan.org>
268

COPYRIGHT AND LICENSE

270       Copyright (C) 2005 by Kevin M. Goess
271
272       Copyright (C) 2005, 2006, 2007, 2008 by Richard Dawe
273
274       This library is free software; you can redistribute it and/or modify it
275       under the same terms as Perl itself, either Perl version 5.8.5 or, at
276       your option, any later version of Perl 5 you may have available.
277
278
279
280perl v5.12.0                      2009-03-05                  File::ExtAttr(3)