table of contents
- bookworm 1.4pl6-15+b1
- testing 1.4pl6-16
- unstable 1.4pl6-16
- experimental 1.4pl6-16.1~exp1
af_retrieve(3) | Attribute Filesystem (AtFS) | af_retrieve(3) |
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.
Fri Jun 25 14:33:18 1993 | AtFS-1.71 |