sourCEntral - mobile manpages

pdf

af_intro

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 DOT Lampen AT cs DOT tu-berlin DOT de)

Technische Universitaet Berlin

Sekr. FR 5-6

Franklinstr. 28/29

D−10587 Berlin, Germany

pdf