.ig Copyright (C) 1993,1994 by the author(s). This software is published in the hope that it will be useful, but WITHOUT ANY WARRANTY for any part of this software to work correctly or as described in the manuals. See the ShapeTools Public License for details. Permission is granted to use, copy, modify, or distribute any part of this software but only under the conditions described in the ShapeTools Public License. A copy of this license is supposed to have been given to you along with ShapeTools in a file named LICENSE. Among other things, this copyright notice and the Public License must be preserved on all copies. Author: Andreas Lampen (Andreas.Lampen@cs.tu-berlin.de) $Header: af_retrieve.3[7.0] Fri Jun 25 14:33:18 1993 andy@cs.tu-berlin.de frozen $ .. .TH af_retrieve 3 "Fri Jun 25 14:33:18 1993" "AtFS-1.71" "Attribute Filesystem (AtFS)" .SH NAME af_find, af_cachefind, af_initattrs, af_getkey, af_dropkey, af_dropset, af_dropall \- AtFS retrieve interface .SH SYNOPSIS #include .sp int af_find (Af_attrs *attrbuf, Af_set *resultset) .sp int af_cachefind (Af_attrs *attrbuf, Af_set *resultset) .sp int af_initattrs (Af_attrs *attrbuf) .sp int af_getkey (char *syspath, char *name, char *type, int gen, int rev, Af_key *aso) .sp int af_dropkey (Af_key *key) .sp int af_dropset (Af_set *set) .sp int af_dropall (void) .sp .SH DESCRIPTION \fIaf_find\fP and \fIaf_cachefind\fP 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 \fIresultset\fP. 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. .LP The retrieve arguments are passed in an attribute buffer (\fIattrbuf\fP). Attrbuf should be initialized by \fIaf_initattrs\fP 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. .LP 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 \fInot\fP set. This makes only sense for \fIaf_locker\fP, when the selection of ASOs that are not locked is desired. .LP On the \fIaf_mode\fP field, a bitwise comparison is performed. In this case, all ASOs will be selected that have \fIat least\fP all required mode bits (given in af_mode) set in their mode field. An exact match is not required. .LP 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 \fIaf_syspath\fP field in the attribute buffer. If no system path is given, the current directory is searched. The fields \fIaf_host\fP in the attribute buffer is ignored in the current implementation. .LP The structure of the attribute buffer is the following: .nf .ta 0.4i 1i 3i 5i typedef struct { initial value char af_host[\s-1MAXHOSTNAMELEN\s+1]; /* hostname (ignored) */ "" char af_syspath[\s-1MAXPATHLEN+1\s+1]; /* system path */ "" char af_name[\s-1MAXNAMLEN+1\s+1]; /* filename */ "*" char af_type[\s-1MAXTYPLEN\s+1]; /* 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; .fi .LP It is possible to pass a list of user defined attributes as retrieve arguments. The list of pointers \fIaf_udattrs\fP in the attribute buffer can be filled with strings of the form name[=value]. The list must be terminated by a nil pointer. .LP The user defined attributes are interpreted in the following way: .TP 5.5c \fIempty list\fP (first entry is a nil pointer) matches every ASO. .TP \fI""\fP (first entry is an empty string) matches every ASO that has \fBno\fP user defined attributes. .TP \fIname\fP[\fI=\fP] matches, if a user defined attribute with the given name is present. .TP \fIname=value\fP matches all ASOs that have a corresponding user defined attribute, that has at least the given value. .LP \fIaf_getkey\fP 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 \fIkey\fP. 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 .LP .RS \fBaf_getkey\ ("",\ "otto",\ "c",\ AF_BUSYVERS,\ AF_BUSYVERS,\ key)\fP .RE .LP leads to the key of the file (busy version) named otto.c in the current directory. .LP .RS \fBaf_getkey ("", "otto", "c", AF_LASTVERS, AF_LASTVERS,\ key)\fP .RE .LP delivers the last saved version (if present) of the history of otto.c. .LP 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 \fIaf_dropkey\fP gives a key back and releases the object version. A retrieved set of keys has to be given back by use of \fIaf_dropset\fP. \fIaf_dropall\fP sets all reference counters for cached object versions to zero, that means, it gives all formerly retrieved keys and sets back. .SH DIAGNOSTICS af_find returns the number of found ASOs. Upon error, -1 is returned and \fIaf_errno\fP is set to the corresponding error number.