Man Linux: Main Page and Category List


       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

       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

       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


       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

       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

       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

       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

       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

       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

       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
              An AtFS operation cannot be performed because the specified  ASO
              is either not locked (see af_lock(3)) or it is locked by another

       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

       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

       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.


       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


       /var/adm/AtFSerrlog, /tmp/AtFSerrlog


       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,
       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 (

           Technische Universitaet Berlin
           Sekr. FR 5-6
           Franklinstr. 28/29
           D-10587 Berlin, Germany