af_sets(3)						    Attribute Filesystem (AtFS) 						af_sets(3)

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 delet-
       ing 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)