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.

AtFS-1.71                                   Fri Jun 25 14:33:20 1993                                  af_sets(3)