Man Linux: Main Page and Category List

NAME

       af_find, af_cachefind, af_initattrs, af_getkey, af_dropkey, af_dropset,
       af_dropall  - AtFS retrieve interface

SYNOPSIS

       #include <atfs.h>

       int af_find (Af_attrs *attrbuf, Af_set *resultset)

       int af_cachefind (Af_attrs *attrbuf, Af_set *resultset)

       int af_initattrs (Af_attrs *attrbuf)

       int af_getkey (char *syspath, char *name, char *type, int gen, int rev,
       Af_key *aso)

       int af_dropkey (Af_key *key)

       int af_dropset (Af_set *set)

       int af_dropall (void)

DESCRIPTION

       af_find  and  af_cachefind  retrieve ASOs by given attributes.  af_find
       operates on source objects and af_cachefind only  on  derived  objects.
       The  keys  of  all  found  ASOs  are  returned  in resultset.  The keys
       returned in resultset are randomly ordered.  af_find  and  af_cachefind
       expect  resultset  to  be  a  pointer  to  an empty set structure. Both
       functions return the number of found ASOs.

       The retrieve arguments are passed in  an  attribute  buffer  (attrbuf).
       Attrbuf  should  be  initialized by af_initattrs before calling af_find
       (resp. af_cachefind). af_initattrs disables all fields in the attribute
       buffer.  The  application  may  then  enable single fields by setting a
       desired attribute value. The initial settings of the single fields  are
       listed below with the structure of the attribute buffer.

       Setting  one of the Af_user fields in the attribute buffer to AF_NOUSER
       causes only ASOs to be selected, where the corresponding user attribute
       is  not set. This makes only sense for af_locker, when the selection of
       ASOs that are not locked is desired.

       On the af_mode field, a bitwise comparison is performed. In this  case,
       all  ASOs  will  be  selected that have at least all required mode bits
       (given in af_mode) set in their mode  field.  An  exact  match  is  not
       required.

       The  first  two fields in the attribute buffer denote the search space.
       Generally, the search space for a retrieve operation  is  a  directory.
       The  directory  name  is given in the af_syspath field in the attribute
       buffer. If no system path is given, the current directory is  searched.
       The  fields  af_host  in the attribute buffer is ignored in the current
       implementation.

       The structure of the attribute buffer is the following:
       typedef struct {                                  initial value
           char  af_host[MAXHOSTNAMELEN];                /* hostname (ignored) */""
           char  af_syspath[MAXPATHLEN+1];               /* system path */""
           char  af_name[MAXNAMLEN+1];                   /* filename */"*"
           char  af_type[MAXTYPLEN]; /* filename extension (type) */"*"
           int   af_gen;             /* generation number */-1
           int   af_rev;             /* revision number */-1
           int   af_state;           /* version state */ -1
           Af_user                   af_owner;           /* owner */{ "", "", "" }
           Af_user                   af_author;          /* author */{ "", "", "" }
           off_t af_size;            /* size of file */  -1
           u_short                   af_mode;            /* protection */0
           Af_user                   af_locker;          /* locker */{ "", "", "" }
           time_t                    af_mtime;           /* date of last modification */-1
           time_t                    af_atime;           /* date of last access */-1
           time_t                    af_ctime;           /* date of last status change*/-1
           time_t                    af_stime;           /* save date */-1
           time_t                    af_ltime;           /* date of last lock change */-1
           char  *af_udattrs[AF_MAXUDAS];                /* user defined attributes */
       } Af_attrs;

       It is possible to pass a list of user defined  attributes  as  retrieve
       arguments.  The list of pointers af_udattrs in the attribute buffer can
       be filled with strings of the form  name[=value].   The  list  must  be
       terminated by a nil pointer.

       The user defined attributes are interpreted in the following way:

       empty list (first entry is a nil pointer)
                             matches every ASO.

       "" (first entry is an empty string)
                             matches  every  ASO  that  has  no  user  defined
                             attributes.

       name[=]               matches, if a user  defined  attribute  with  the
                             given name is present.

       name=value            matches  all  ASOs that have a corresponding user
                             defined attribute, that has at  least  the  given
                             value.

       af_getkey  builds  up  an  object  key  by  a combination of attributes
       (pathname, name, type, generation number, revision number  and  variant
       name)  uniquely  identifying  a source ASO. Upon successful completion,
       the found object key  is  returned  in  the  buffer  key.   Instead  of
       explicit  version numbers, you can pass the pseudo-numbers AF_BUSYVERS,
       AF_FIRSTVERS or AF_LASTVERS to  af_getkey.   af_getkey  works  only  on
       source objects. The call

              af_getkey ("", "otto", "c", AF_BUSYVERS, AF_BUSYVERS, key)

       leads to the key of the file (busy version) named otto.c in the current
       directory.

              af_getkey ("", "otto", "c", AF_LASTVERS, AF_LASTVERS, key)

       delivers the last saved version (if present) of the history of  otto.c.

       After  having  retrieved  a  key  or  a  set  of keys, the data for the
       corresponding object version(s) remains cached in memory as long as the
       application  does  not  explicitly  give  the  key  back.  The function
       af_dropkey gives a  key  back  and  releases  the  object  version.   A
       retrieved  set  of  keys  has  to  be  given back by use of af_dropset.
       af_dropall sets all reference counters for cached  object  versions  to
       zero, that means, it gives all formerly retrieved keys and sets back.

DIAGNOSTICS

       af_find  returns  the  number of found ASOs. Upon error, -1 is returned
       and af_errno is set to the corresponding error number.