HP C/iX Library Reference Manual (30026-90004)

364 Chapter5
HP C/iX Library Function Descriptions
tfind
tfind
Searches for a specified entry in a binary search tree.
Syntax
#include <search.h>
void *tfind (void * key , void ** rootp , int (* compar )());
Parameters
key A pointer to an item to be searched for. If there is an item in the tree equal
to *
key (the value pointed to by key ), a pointer to the item found is
returned. Otherwise, a null pointer is returned. Only pointers are copied,
so the calling function must store the data.
rootp A pointer to a variable that points to the root of the tree. A null value for
the variable pointed to by
rootp indicates an empty tree.
compar All comparisons are done with the function compar , which must be
supplied by the programmer. This function is called with two arguments,
the pointers to the elements being compared.
It returns an integer less than, equal to, or greater than zero, according to
whether the first argument is to be considered less than, equal to, or
greater than the second argument.
The comparison function does not need to compare every byte, so arbitrary
data can be contained in the elements in addition to the values being
compared.
Return Values
If successful, tfind() returns a pointer to the value pointed to by key . Otherwise, a null
pointer is returned either if the entry was not found or if
rootp is NULL on entry.
Description
The tfind function searches a binary search tree for the specified entry. The tfind(),
tsearch(), tdelete(), and twalk() functions manage binary search trees generalized
from Knuth Algorithms T and D (6.2.2) described in The Art of Computer Programming,
Vol3 (Sorting and Searching) by Donald Ervin Knuth (Reading, Mass.:Addison-Wesley,
1973).
All comparisons are done with the function
compar , which must be supplied by the
programmer.
The pointers to the key and the root of the tree should be of type pointer-to-element, and
should be cast to type pointer-to-character. Similarly, although declared as type
pointer-to-character, the value returned should be cast into type pointer-to-element.
If the calling function alters the pointer to the root, results are unpredictable.