Provided by: atfs-dev_1.4pl6-13_amd64 bug

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