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.