.ig
 Copyright (C) 1993,1994 by the author(s).
 
 This software is published in the hope that it will be useful, but
 WITHOUT ANY WARRANTY for any part of this software to work correctly
 or as described in the manuals. See the ShapeTools Public License
 for details.

 Permission is granted to use, copy, modify, or distribute any part of
 this software but only under the conditions described in the ShapeTools 
 Public License. A copy of this license is supposed to have been given
 to you along with ShapeTools in a file named LICENSE. Among other
 things, this copyright notice and the Public License must be
 preserved on all copies.


Author: Andreas Lampen (Andreas.Lampen@cs.tu-berlin.de)

$Header: af_sets.3[7.0] Fri Jun 25 14:33:20 1993 andy@cs.tu-berlin.de frozen $
..
.TH af_sets 3 "Fri Jun 25 14:33:20 1993" "AtFS-1.71" "Attribute Filesystem (AtFS)"
.SH 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
.SH SYNOPSIS
#include <atfs.h>
.sp
int af_initset (Af_set *set)
.sp
int af_nrofkeys (Af_set *set)
.sp
int af_setgkey (Af_set *set, int position, Af_key *key)
.sp
int af_setaddkey (Af_set *set, int position, Af_key *key)
.sp
int af_setrmkey (Af_set *set, Af_key *key)
.sp
int af_setposrmkey (Af_set *set, int position)
.sp
int af_sortset (Af_set *set, char *attrname)
.sp
int af_subset (Af_set *set, Af_attrs *attrbuf, Af_set *subset)
.sp
int af_copyset (Af_set *source, Af_set *destination)
.sp
int af_intersect (Af_set *set1, Af_set *set2, Af_set *newset)
.sp
int af_union (Af_set *set1, Af_set *set2, Af_set *newset)
.sp
int af_diff (Af_set *set1, Af_set *set2, *Af_set newset)
.sp
.SH DESCRIPTION
Sets in AtFS are ordered collections of keys. The structure of sets is
the following
.LP
.RS
.nf
typedef struct {
	int	af_nkeys;
	int	af_setlen;
	Af_key	*af_klist;
} Af_set;
.fi
.RE
.LP
The list of keys in a set is a linear list, residing in allocated
memory. The list has no holes, so that positions \fI0\fP through
\fIaf_nkeys-1\fP are occupied with valid keys. Set functions returning
a set require a pointer to an empty set structure as argument.
.LP
\fIaf_initset\fP initializes a set.
.LP
\fIaf_nrofkeys\fP returns the number of valid keys in the given \fIset\fP.
.LP
\fIaf_setgkey\fP delivers the filekey, stored at position
\fIposition\fP in the identified set. The result is passed in the
buffer \fIkey\fP. 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:
.nf
	\fCAf_key key;
	Af_set set;
	af_initset (&set);
	...
	for (i = 0; i < af_nrofkeys (&set); i++) {
		af_setgkey (&set, i, &key);
		/* process key */
		...
	}\fP
.fi
.LP
\fIaf_setaddkey\fP 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 \fIposition\fP argument
leads to adding the new filekey at the end of the set.
.LP
\fIaf_setrmkey (af_setposrmkey)\fP removes the given filekey (the filekey at
position \fIposition\fP) 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.
.LP
\fIaf_sortset\fP 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.
.LP
In \fIatfs.h\fP 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.
.LP
\fIaf_subset\fP 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
(\fIattrbuf\fP) with all desired attributes set to an appropriate
value as argument. The attribute buffer should be initialized by
\fIaf_initattrs\fP (manual page af_retrieve(3)) beforehand. af_subset
returns it's result in a new set, the original set remains unchanged.
.LP
\fIaf_copyset\fP for copying sets (really! =:-).
.LP
\fIaf_intersect\fP, \fIaf_union\fP and \fIaf_diff\fP
build intersections, unions, and differences between two sets.
The result is a new set, where all keys taken from the first argument
set (\fIset1\fP) occur first, and the keys from the second argument set
(\fIset2\fP) afterwards. You may gibe one of set1 or set2 as
\fIresultset\fP. In that case, the original set get lost and is dropped
implicitely.
.LP
Sets generated by af_copyset, af_subset, af_intersect, af_union, or
af_diff should be released by \fIaf_dropset\fP as soon as they are not
used any longer.
.SH SEE ALSO
af_retrieve(3)
.SH DIAGNOSTICS
Upon error, \-1 or a nil pointer (depending on the return type) is returned
and \fIaf_errno\fP is set to the corresponding error number.