Parent:
[91419d]
(diff)
Download this file
Intro.dox
111 lines (87 with data), 4.5 kB
/** @mainpage pxattr: portable extended attributes C++ programming interface
@authors Jean-Francois Dockes <jfd@recoll.org>
@section intro Introduction
Extended attributes are arbitrarily named pieces of data associated
with a file and managed by the file system.
The names and the values for the attributes are freely chosen by
applications and/or users, with very few restrictions. Many recent systems
and filesystems support extended attributes, but the interfaces used to
manage them are far from identical.
Linux, FreeBSD and Mac OS X all provide similar extended attributes
functionality.
@section pxattr Pxattr
The pxattr package provides a portable programming interface for managing
file extended attributes on all three systems. It consists in a single C++
module (one source and one include file), which is to be included in the
application source code (being too trivial to justify a library).
Calls are provided to read, modify or delete extended attributes. Check the
Namespaces above for more detail.
Linux note: on Linux, user attributes are distinguished by having a
"user." prefix in their name. On Mac OS X and FreeBSD, the user and
other name spaces are distinguished by argument to the library calls.
pxattr hides the "user." prefix on Linux, so that you should not specify it
when reading or setting a value.
@par Command line program
The C++ file can also be compiled into program which provides a handy way
to manage attributes from the command line.
Especially, the *pxattr* command can produce a dump of the extended
attributes for a directory tree. This dump can then be restored if the tree
has been copied elsewhere. This works across the three platforms and can
provide a workaround for the current lack of common extended attributes
archiving commands. Method:
cd /just/above/my/treedir/..
pxattr -lR treedir > treedir/extattr_archive.txt # or whatever...
tar cf /tmp/myarchive.tar treedir
On the target:
tar xf myarchive.tar
pxattr -S treedir/extattr_archive.txt
Notice that I took care to preserve the relative paths when doing the
backup and the restore. In a pinch, the dump could be edited to fix the
paths (use sed or emacs), the dump format is line-oriented but as binary as
the extended attributes contents, with just a few escaped characters.
@par License
Pxattr is free software, with an MIT-type license, use and redistribute
freely.
@par Download pxattr
<a href="pxattr-2.1.0.tar.gz">pxattr-2.1.0.tar.gz</a>
@par Source repository
<a href="https://bitbucket.org/medoc/pxattr">On BitBucket</a>
@par Building the driver
You will need g++ and make (and nothing else as far as I know).
Typing "make" inside the source directory should then be enough.
@par Note
The previous version of the library had a bug which had it adding the
"user." prefix to names on other platforms. This was not a main issue
inside pxattr, but posed a compatibility problem when using raw system
utilities or moving files between systems. Version 2.0 fixes this
problem but the change means that it is incompatible with attributes
created by pxattr 1.0 (which contain the "user." prefix, which will
appear when listing the attributes and now need to be added when
fetching a value. You can use "make CXXFLAGS=-DCOMPAT1 to force
the 1.0 behaviour with 2.0. This does not make a lot of sense though,
because you're just as well staying with 1.0 then, as nothing else has
changed.
@par Licensing
Copyright (c) 2009-2013 Jean-Francois Dockes
@par
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:
@par
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
@par
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
*/