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.