Guardian Native C Library Calls Reference Manual (G06.28+, H06.05+)

tsearch(3) Guardian Native C Library Calls Reference Manual
NAME
tsearch - Builds and searches a binary search tree
LIBRARY
G-series native Guardian processes: $SYSTEM.SYSnn.ZCRTLSRL
G-series native OSS processes: /G/system/sysnn/zcrtlsrl
H-series native Guardian processes: $SYSTEM.ZDLLnnn.ZCRTLDLL
H-series OSS processes: /G/system/zdllnnn/zcrtldll
SYNOPSIS
#include <search.h>
void *tsearch(
const void *key,
void **rootp,
int (*compar) (const void *, const void *) );
PARAMETERS
key Points to a key that specifies the entry to be searched in the binary tree.
rootp Points to a variable that points to the root of the binary tree.
compar Specifies the name (that you supply) of a comparison function (strcmp(), for
example). This function is called with two parameters that point to the data
undergoing comparison in the binary tree.
DESCRIPTION
The tsearch(), tfind(), tdelete(), and twalk() functions are used to operate on binary search
trees. Comparisons are done with a function that you supply. The address of that supplied func-
tion is passed as the compar parameter in the tsearch(), tfind(), and tdelete() functions. The
compare function is called with two parameters that point to objects that are compared during the
tree search. This function returns an integer less than, equal to, or greater than 0 (zero), depend-
ing on whether the object pointed to by the first parameter is less than, equal to, or greater than
the object pointed to by the second parameter.
The tsearch() function is used to build and search a binary tree. The key parameter is a pointer
to an entry that is to be found in the tree or stored in the tree. When an entry in the tree is found
that matches key, a pointer to the entry is returned. If a matching entry is not found, the value
pointed to by key is inserted into the tree in its proper place, and a pointer to the the new entry is
returned. The first field in this new entry is a pointer to this new key. (Because the value
returned is a pointer to key and key itself is a pointer, the value returned is a pointer to a pointer.)
Only pointers are copied, so the calling routine must store the data. The rootp parameter points
to a variable that points to the root of a binary tree. A null pointer value for the variable pointed
to by rootp denotes an empty tree; in this case the variable is set to point to the node that will be
at the root of the new tree.
NOTES
The tsearch() function is reentrant, but care should be taken to ensure that the function supplied
as the argument to compar is also reentrant.
The comparison function does not need to compare every byte; consequently, arbitrary data can
be contained in the searched keys in addition to the values undergoing comparison.
7−34 Hewlett-Packard Company 527192-007