NAME
AtFS - introduction to AtFS library functions and error codes
SYNOPSIS
#include <atfs.h>
int af_errno
DESCRIPTION
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:
·
The object key that uniquely identifies an ASO (version). The
structure of this type can be different in different implementations
of AtFS. Consequently, application programs should handle this type as
opaque type and should not access single fields.
·
A set descriptor represents a set of object keys. A set descriptor
contains information about the size of the set and a list of object
keys in the set.
·
The user identification represents a user. As AtFS realizes a simple
network user concept, it does not identify users by their UNIX user
id, but rather by the user name and the domain where this name is
valid. See af_afuser (manual page af_misc(3)) for details.
·
An attribute buffer is capable to hold all attributes of a software
object (standard attributes and user defined attributes). Attribute
buffers have two different purposes. First, they can hold a retrieve
pattern, i.e. they may be (partially) filled with desired attribute
values and then be passed as argument to a retrieve operation (af_find
and af_cachefind - manual page af_retrieve(3)). Second, an attribute
buffer is used to return all attributes of an identified ASO on
demand.
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.
ERROR CODES
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.
AF_ESYSERR (-2) Error during execution of system library command or
system call
A called system library function or system call returned with an
error condition. See errno for a more precise error
specification.
AF_EACCES (-3) permission denied
An attempt was made to perform an operation (e.g. open a file)
without appropriate permissions.
AF_EARCHANGED (-4) archive file has changed since last read
One of the archive files you are operating on has been modified
by another process since your process has read it from disk. In
this case, AtFS refuses to store your changes because this would
destroy the modifications made by the other process. In order
to make your desired changes happen, you have to rerun your
application.
AF_EBUSY (-7) Specified ASO must not be a busy version
Some AtFS-operations cannot be performed on ASOs which have the
state AF_BUSY.
AF_EDERIVED (-8) Specified ASO must not be a derived object
Some AtFS-operations (eg. af_lock - manual page af_lock(3),
af_newgen - manual page af_version(3)) cannot be performed on
ASOs stored in derived object caches.
AF_EINVKEY (-9) invalid object key
An invalid object key (eg. nil pointer) was passed to an AtFS
function.
AF_EINVSET (-10) invalid set descriptor
An invalid set descriptor (eg. nil pointer) was passed to an
AtFS function.
AF_EINVUSER (-11) invalid user
An invalid user structure or user id was passed to an AtFS
operation.
AF_EINVVNUM (-12) Bad version number
An attempt was made to set a version number, that contradicts
the AtFS version numbering philosophy, to an ASO. You cannot
change the version number of an ASO into a version number that
is "smaller" than the one given by the system.
AF_EMISC (-15) miscellaneous errors
This error code is set when an error occurs that does not fit in
any of the other error categories. See your error logging file
(/usr/adm/AtFSerrlog of /tmp/AtFSerrlog) for a detailed
description of the error. af_perror (manual page af_error(3))
also gives a diagnostic message explaining the error.
AF_EMODE (-16) invalid mode
The function af_setattr (manual page af_attrs(3)) requires a
change mode. This error condition complains about an invalid
mode given to this function.
AF_ENOATFSDIR (-17) AtFS subdirectory missing or not writable
There is no place where AtFS can create it’s archive files.
Either a global archive path should be defined (see
af_setarchpath - manual page af_misc(3)) or a subdirectory named
AtFS should be present and writable.
AF_ENOKEY (-18) key does not exist in set
A specified key that shall be removed from a keyset does not
exist in the concerning set.
AF_ENOPOS (-19) invalid position in set
A specified position in a keyset (keysets are organized as
arrays of object keys) lies beyond the bounds of the concerning
set.
AF_ENOREV (-20) specified revision does not exist
A revision - uniquely identified by a set of attributes (eg.
af_getkey - manual page af_retrieve(3)) - does not exist in the
current search space.
AF_ENOTBUSY (-21) specified ASO is not busy version
Some AtFS operations (eg. af_setbusy - manual page
af_version(3)) require the key of a busy ASO as input parameter.
If you pass key of a non-busy ASO, the function sets this error
code.
AF_ENOTDERIVED (-22) specified ASO is no derived object
An attempt was made to restore an object that in not stored in a
derived object cache.
AF_ENOTLOCKED (-23) specified ASO is not locked or locked by another
user
An AtFS operation cannot be performed because the specified ASO
is either not locked (see af_lock(3)) or it is locked by another
user.
AF_ENOTREGULAR (-24) specified ASO is no regular file
With this error number AtFS refuses to generate versions of non-
regular UNIX files such as directories, special files and
sockets.
AF_ENOTVERS (-25) specified ASO has no versions
Typically, this error occurs if an operation requiring at least
one saved revision (eg. af_newgen - manual page af_version(3))
is applied on a versionless file.
AF_ENOUDA (-26) user defined attribute does not exist
A user defined attribute with the given name does not exist.
AF_ESAVED (-27) saved versions cannot be modified
An attempt was made to open a non-busy version with write
access.
AF_ESTATE (-28) invalid state transition
The Attribute File System’s built in revision-states model
allows only well defined revision state changes.
AF_EWRONGSTATE (-31) wrong state
Some AtFS operations can only be performed on ASOs with a
specific version state.
The error codes indicating real trouble:
AF_EDELTA (-32) Error during delta operation
Some error occurred during invocation of the delta processor.
AF_EINCONSIST (-33) Archive file inconsistent
The data in the archive file are corrupted. This may have
happened by editing the archive file or by malfunction of an
AtFS operation. Try atfsrepair ti fix it.
AF_EINTERNAL (-34) internal error
Please inform your local trouble shooting service, go to your
favorite pub and order a beers. Cheers !
AF_ENOATFSFILE (-35) No AtFS file
Archive file lost.
LIST OF FUNCTIONS
Name Appears on PageDescription
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.3free 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.3return value of time attribute
af_retuserattr af_attrs.3return 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.3set 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.3remove 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.3begin 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
FILES
/var/adm/AtFSerrlog, /tmp/AtFSerrlog
SEE ALSO
intro(2), intro(3)
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
BUGS
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.
AUTHOR
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