Man Linux: Main Page and Category List

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.