| af_intro(3) | Attribute Filesystem (AtFS) | af_intro(3) |
AtFS - introduction to AtFS library functions and error codes
#include <atfs.h>
int af_errno
The following manual pages (named af*) describe the library functions of the Attribute File System (AtFS).
AtFS is an extension to the UNIX file system interface that allows the storage of files as complex of content data and an arbitrary number of associated attributes. Attributes are either standard attributes or user defined attributes (also called application defined attributes). A data complex consisting of contents data and attributes, is called Attributed Software Object (ASO). In the following they are also referred to as object versions or simply versions. AtFS has a built-in version control system that manages object histories. A object history consists of an optional busy version and a number of saved versions. The busy version is represented by an ordinary alterable UNIX file. It can be accessed via AtFS and UNIX file system operations. Saved versions come into being by making a copy of the current state of the busy version. They can be stored as source versions or as derived versions.
Source versions are typically composed manually (e.g. by use of a text editor). AtFS stores source versions as immutable objects. Once saved, they cannot be modified any longer. Saved versions are stored in archive files, residing in a subdirectory named AtFS. AtFS maintains two archive files for each history of source versions - one holding the attributes and the other holding the data. To save disk space, the versions in an archive are stored as deltas, that means, only differences between two successive versions are stored.
Derived versions are typically derived automatically (e.g. by a compiler) from a source version and thus be reproducible at any time. They are kept in a derived object cache a data store of limited size that is administered in a cache fashion. When space runs short, old versions are cleaned out of the cache according to a defined policy. Check af_cache(3) for details.
AtFS makes no assumptions whether a copy of a busy object shall be stored as source object or as derived object. The application has to decide that by calling the appropriate function (af_saverev - manual page af_version(3) or af_savecache - manual page af_cache(3)).
The main data types for AtFS applications are:
There are several ways for an AtFS application to get an object key pointing to a specific object version. The most important is the function af_getkey (manual page af_retrieve(3)), that returns a key for an explicitly named version. After having retrieved a key, the data for that object version remains cached in memory as long as the application does not explicitly give the key back. The function af_dropkey (manual page af_retrieve(3)) gives a key back and releases the object version. A retrieved set of keys has also to be given back by use of af_dropset (manual page af_retrieve(3)). af_dropall (manual page af_retrieve(3)) sets all reference counters for cached object versions to zero, that means, it gives all formerly retrieved keys and sets back. In the case, that any attribute, or the contents data of a cached object version is modified on disk by another application, the data in the cache is automatically updated. In that case, a warning is written to the error log file.
For handling sets of keys, AtFS provides a full set algebra with functions for adding and deleting single keys, sorting, building subsets, intersections, unions and differences of sets.
The built-in version control functionality features a status mode for versions. Each object version has a certain state, one of busy, saved, proposed, published, accessed and frozen. The already known busy version always has the state busy, while when previously referencing a saved versions we meant a version that can have any state from saved to frozen. AtFS does not enforce any specific semantics with the version state. It is rather a help for applications to implement a classification for versions. Another part of the version control functionality is a locking facility. Adding a new version to an existing object history always requires a lock on the most recent version or the generation to which the version shall be added. Locks can be used for implementing a synchronization mechanism for concurrent updates to one object history.
A user defined attribute (or application defined attribute) has the general form name[=value [value [...]]]. It has a name and a (possibly empty) list of values. The name may consist of any characters (even non-alphanumeric) but an equal sign (=). The equal sign is the delimiter between name and value. The attribute value may not contain Ctrl-A (\001) characters. Although AtFS promises the storage of an arbitrary number of user defined attributes, the current implementation limits their number to 255.
Most of the AtFS calls have one or more error returns. An error is indicated by a return value that is either -1 or a nil pointer, depending on the return type of the function. If one of the functions returns with an error, the variable af_errno is set to indicate the appropriate error number. af_errno is not cleared upon successful calls.
The following is a complete collection of the error numbers defined in atfs.h. The first list contains return values indicating common error conditions like implausible arguments passed to an AtFS function or permission problems. The error codes listed in the second list point to serious trouble, which can either be an internal error in AtFS or a corrupted archive file. The occurrence of an serious problem is recorded in an error protocol (/usr/adm/AtFSerrlog). On machines without syslog(3) switched on for AtFS, the error protocol is located in a /tmp/AtFSerrlog.
The error codes indicating real trouble:
Name Appears on Page Description
af_abort af_transact.3 abort transaction af_access af_history.3 test existence of history af_afname af_misc.3 get ASO name from UNIX path af_afpath af_misc.3 get ASO syspath from UNIX path af_aftype af_misc.3 get ASO type from UNIX path af_afuser af_misc.3 get AtFS user from UNIX uid af_allattrs af_attrs.3 get all attributes of ASO af_cachefind af_retrieve.3 find derived objects by attributes af_cachenames af_history.3 return list of names in derived object cache af_cachesize af_cache.3 define object cache size policy af_chauthor af_protect.3 change author of ASO af_chmod af_protect.3 change protection of ASO af_chowner af_protect.3 change owner of ASO af_cleanup af_error.3 do cleanup after error af_close af_files.3 close ASO contents af_commit af_transact.3 commit transaction af_copyset af_sets.3 copy sets af_crkey af_files.3 create object key for UNIX-file af_diff af_sets.3 build difference between two sets of object keys af_dropall af_retrieve.3 drop all accessed object keys af_dropkey af_retrieve.3 drop object key af_dropset af_retrieve.3 drop set of object keys af_errmsg af_error.3 return AtFS- or system error message af_errno af_error.3 global error code variable af_establish af_files.3 establish ASO as UNIX file af_find af_retrieve.3 find ASOs by attributes af_freeattr af_attrs.3 free memory associated with attribute value af_freeattrbuf af_attrs.3 free memory associated with attribute buffer af_getkey af_retrieve.3 get key by unique attributes af_histories af_history.3 return list of history names matching pattern af_initattrs af_retrieve.3 initialize attribute buffer af_initset af_sets.3 initialize set af_intersect af_sets.3 build intersection between two sets of object keys af_isstdval af_attrs.3 check if attribute is from a standard attribute af_lock af_lock.3 set lock on ASO af_newgen af_version.3 increase generation number of ASO af_nrofkeys af_sets.3 return number of keys in set of object keys af_open af_files.3 open ASO contents af_perror af_error.3 report AtFS- or system error af_predsucc af_version.3 get successor or predecessor of version af_restore af_files.3 restore derived ASO af_retattr af_attrs.3 return value of attribute as string af_retnumattr af_attrs.3 return value of numeric attribute af_rettimeattr af_attrs.3 return value of time attribute af_retuserattr af_attrs.3 return value of user attribute af_rm af_files.3 remove ASO af_rnote af_note.3 return note attribute af_savecache af_cache.3 save derived object to cache af_saverev af_version.3 save busy version of source object af_setaddkey af_sets.3 add key to set of object keys af_setarchpath af_misc.3 set path for location of archives af_setattr af_attrs.3 set user defined attribute af_setbusy af_version.3 set version busy af_setgkey af_sets.3 get key from set of object keys af_setposrmkey af_sets.3 remove key (id. by position) from set of object keys af_setrmkey af_sets.3 remove key from set of object keys af_snote af_note.3 modify note attribute af_sortset af_sets.3 sort set of object keys af_sstate af_version.3 set version state af_subset af_sets.3 build subset of set of object keys af_svnum af_version.3 set version number af_testlock af_lock.3 see if ASO is locked af_transaction af_transact.3 begin transaction af_union af_sets.3 build union of two sets of object keys af_unlock af_lock.3 remove lock from ASO af_version af_misc.3 return identification of current AtFS version
/var/adm/AtFSerrlog, /tmp/AtFSerrlog
Andreas Lampen and Axel Mahler
An Object Base for Attributed Software Objects
Proceedings of the Autumn '88 EUUG Conference (Cascais, October 3-7)
European UNIX System User Group, London 1988
For an outlook on a totally new implementation of the AtFS idea,
have a look at:
Andreas Lampen
Advancing Files to Attributed Software Objects
Proceedings of USENIX Technical Conference (Dallas TX, January 21-25, 1991)
USENIX Association, Berkeley CA, January 1991
The built in archive file locking to prevent concurrent updates is very simple and my lead to confusing situations. It may happen that changes will not be saved to disk. See the error conditions AF_EARCHANGED and AF_EARLOCKED for more details.
Andreas Lampen, Tech. Univ. Berlin (Andres.Lampen@cs.tu-berlin.de)
Technische Universitaet Berlin
Sekr. FR 5-6
Franklinstr. 28/29
D-10587 Berlin, Germany
| Fri Jun 25 14:32:56 1993 | AtFS-1.71 |