NAME¶
af_initset, af_nrofkeys, af_setgkey, af_setaddkey, af_setrmkey, af_setposrmkey,
af_sortset, af_subset, af_copyset, af_intersect, af_union, af_diff - AtFS
operations on key sets
SYNOPSIS¶
#include <atfs.h>
int af_initset (Af_set *set)
int af_nrofkeys (Af_set *set)
int af_setgkey (Af_set *set, int position, Af_key *key)
int af_setaddkey (Af_set *set, int position, Af_key *key)
int af_setrmkey (Af_set *set, Af_key *key)
int af_setposrmkey (Af_set *set, int position)
int af_sortset (Af_set *set, char *attrname)
int af_subset (Af_set *set, Af_attrs *attrbuf, Af_set *subset)
int af_copyset (Af_set *source, Af_set *destination)
int af_intersect (Af_set *set1, Af_set *set2, Af_set *newset)
int af_union (Af_set *set1, Af_set *set2, Af_set *newset)
int af_diff (Af_set *set1, Af_set *set2, *Af_set newset)
DESCRIPTION¶
Sets in AtFS are ordered collections of keys. The structure of sets is the
following
typedef struct {
int af_nkeys;
int af_setlen;
Af_key *af_klist;
} Af_set;
The list of keys in a set is a linear list, residing in allocated memory. The
list has no holes, so that positions
0 through
af_nkeys-1 are
occupied with valid keys. Set functions returning a set require a pointer to
an empty set structure as argument.
af_initset initializes a set.
af_nrofkeys returns the number of valid keys in the given
set.
af_setgkey delivers the filekey, stored at position
position in
the identified set. The result is passed in the buffer
key. Typically
you use af_setgkey to run through a set and perform a special action on each
key. The following code sequence does this job:
Af_key key;
Af_set set;
af_initset (&set);
...
for (i = 0; i < af_nrofkeys (&set); i++) {
af_setgkey (&set, i, &key);
/* process key */
...
}
af_setaddkey introduces a new filekey to an existing set at the given
position. All following keys are moved back by one position. The constant
AF_LASTPOS given as
position argument leads to adding the new filekey
at the end of the set.
af_setrmkey (af_setposrmkey) removes the given filekey (the filekey at
position
position) from the specified set. Holes generated by deleting
single keys from a set are eliminated by condensing the set. All following
keys are moved one position forth in the set.
af_sortset sorts a given set of object keys by the values of the named
attribute. The set is sorted in increasing order. Increasing order means, that
the lowest value occurs first in the set. Af_user structures are compared by
username first and by userdomain, if the names are equal (user host will not
be taken into account). Version numbers are ordered in natural order, busy
versions first.
In
atfs.h you can find a list of attribute names naming the standard
attributes. All other attribute names are presumed to be user defined
attributes. While sorting by the values of an user defined attribute, all ASOs
that do not have the named attribute are added at the end of the resulting
(sorted) set. Sorting of user defined attributes with multiple values bases on
simple text comparison with the order of the values taken as it is. The length
of the given attribute name is limited. This limit is defined by the constant
AF_UDANAMLEN in atfs.h.
af_subset does a retrieve operation (similar to af_find - manual page
af_retrieve(3)) on a given set of object keys. Af_subset takes an attribute
buffer (
attrbuf) with all desired attributes set to an appropriate
value as argument. The attribute buffer should be initialized by
af_initattrs (manual page
af_retrieve(3)) beforehand. af_subset returns
it's result in a new set, the original set remains unchanged.
af_copyset for copying sets (really! =:-).
af_intersect,
af_union and
af_diff build intersections,
unions, and differences between two sets. The result is a new set, where all
keys taken from the first argument set (
set1) occur first, and the
keys from the second argument set (
set2) afterwards. You may gibe one
of set1 or set2 as
resultset. In that case, the original set get lost
and is dropped implicitely.
Sets generated by af_copyset, af_subset, af_intersect, af_union, or af_diff
should be released by
af_dropset as soon as they are not used any
longer.
SEE ALSO¶
af_retrieve(3)
DIAGNOSTICS¶
Upon error, -1 or a nil pointer (depending on the return type) is returned and
af_errno is set to the corresponding error number.