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

leads to the key of the file (busy version) named otto.c in the current directory.

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.