NAME

Linux::UserXAttr - Support for extended file attributes on Linux

SYNOPSIS

 use Linux::UserXAttr qw/:all/;

 $success=setxattr $filename_or_handle, $name, $value, $flags;
 $success=lsetxattr $filename, $name, $value, $flags;
 $value=getxattr $filename_or_handle, $name;
 $value=lgetxattr $filename, $name;
 @names=listxattr $filename_or_handle;
 @names=llistxattr $filename;
 $success=removexattr $filename_or_handle, $name;
 $success=lremovexattr $filename, $name;

DESCRIPTION

This module implements a very thin layer around the extended attributes syscalls on Linux. See setxattr(2), getxattr(2), listxattr(2) and removexattr(2) for more information.

Due to varying support in different kernels the test suite of this module is really simple. It verfies that the functions and constants are exported but does not call the actual syscalls. If you smell a wumpus try strace, e.g.:

 strace perl -MLinux::UserXAttr=:all -le 'setxattr qw/. user.name value/'

and look up the syscall like:

 setxattr(".", "user.name", "value", 5, 0) = 0

Functions

$success=setxattr $filename_or_handle, $name, $value, $flags

creates or modifies the extended attribute $name and sets its value to $value. $flags can be used to refine the semantics of the operation. The 2 constants are allowed XATTR_CREATE and XATTR_REPLACE.

For more information see the setxattr(2) manpage.

$filename_or_handle may be a file or directory name or an open file or directory handle.

On success true is returned. On failure the empty list is returned and $! set accordingly.

Note, support for extended attributes and particularly for $flags may vary for different kernels.

$success=lsetxattr $filename, $name, $value, $flags

same as setxattr but fails if $filename is a symlink.

$value=getxattr $filename_or_handle, $name

reads an extended attribute.

On failure the empty list is returned and $! set accordingly.

$value=lgetxattr $filename, $name

same as getxattr but fails if $filename is a symlink.

@names=listxattr $filename_or_handle

returns a list of names of extended attributes.

@names=llistxattr $filename

same as listxattr but fails if $filename is a symlink.

$success=removexattr $filename_or_handle, $name

removes the extended attribute $name.

On success true is returned. On failure the empty list is returned and $! set accordingly.

$success=lremovexattr $filename, $name

same as removexattr but fails if $filename is a symlink.

EXPORT

None by default.

On demand all functions and constants are exported.

Export tags

:flags

exports XATTR_CREATE and XATTR_REPLACE

:functions

exports setxattr, lsetxattr, getxattr, lgetxattr, listxattr, llistxattr, removexattr and lremovexattr.

:all

all of the above

SEE ALSO

Linux manual.

AUTHOR

Torsten Förtsch, <torsten.foertsch@gmx.net>

COPYRIGHT AND LICENSE

Copyright (C) 2011 by Torsten Förtsch

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.12.3 or, at your option, any later version of Perl 5 you may have available.

cpanm Linux::UserXAttr

perl -MCPAN -e shell
install Linux::UserXAttr