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
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.