af_find(3) af_dropset,

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.

LAST SEARCHED