--- name: "af_retrieve" section: "3" platform: "linux" package: "atfs-dev" version: "1.4pl6-15+b1" release: "Debian 12 (Bookworm)" platforms: ["linux"] url: "https://new.carta.tech/af_retrieve" --- # af\_retrieve(3) AtFS retrieve interface ## NAME af\_find, af\_cachefind, af\_initattrs, af\_getkey, af\_dropkey, af\_dropset, af\_dropall - AtFS retrieve interface ## SYNOPSIS \#include \ 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.