tsearch()

build and access a binary tree 

Function

SYNOPSIS

#include <search.h>

void *tsearch(void *key, void **rootp, int(*compar)(const void *, const void *);

DESCRIPTION

tsearch() is used to build and access a binary search tree. key is a pointer to a node to find or insert. rootp is the root of the tree to be traversed. If there is a node in the tree equal to *key (the value pointed to by key), a pointer to this node is returned. Otherwise, *key is inserted, and a pointer to it returned. Only pointers are copied, so the calling routine must store the data. rootp points to a pointer to the root of the tree. A null value for *rootp denotes an empty tree; in this case, key becomes the root of the new tree.

All comparisons are done with a user-supplied routine, compar. This routine is called with two arguments, the pointers to the elements being compared. It returns an integer less than, equal to, or greater than 0, according to whether the first argument is to be considered less than, equal to, or greater than the second argument. The comparison function need not compare every byte, so arbitrary data may be contained in the elements in addition to the values being compared.

If the calling function alters rootp, results are unpredictable.

PARAMETERS

key 

Points to the node to find or insert.

rootp 

Points to a pointer to the root of the tree. A null value for the variable pointed to by rootp denotes an empty tree.

compar 

Is the comparator function.

RETURN VALUES

If the node is found, tsearch() returns a pointer to it. If not, tsearch() returns a pointer to the inserted node. tsearch() returns a null pointer, if there is not enough space available to create a new node or if rootp is null on entry.

CONFORMANCE

UNIX 98.

MULTITHREAD SAFETY LEVEL

MT-Safe.

PORTING ISSUES

None.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

SEE ALSO

Functions:
bsearch(), hsearch(), tdelete(), tfind(), twalk()

PTC MKS Toolkit 10.4 Documentation Build 39.