af_find, af_cachefind, af_initattrs, af_getkey, af_dropkey, af_dropset, af_dropall − AtFS retrieve interface
#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)
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.
af_find returns the number of found ASOs. Upon error, -1 is returned and af_errno is set to the corresponding error number.