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.