tsearch documentation

[Ingo Krabbe <ikrabbe dot ask at web dot de>]

Hi,

I think I stumbled over this unclearness at least the second time now, where
the return value of tsearch is described (info:glibc):

    The return value is a pointer to the matching element in the tree.  If a
    new element was created the pointer points to the new data (which is in
    fact KEY).  If an entry had to be created and the program ran out of space
    `NULL' is returned.

Actually the pointer doesn't point to the new data but points to the KEY
pointer, which has to be assigned before.  Of course this KEY pointer is
embedded into an internal record, which is the new data element, the return
value shows.

As the comparison between

	void** ret, *KEY;
	ret = tsearch( KEY, &root, compare_function );

*ret and KEY will reveal if the returned element points to a new item or to a
found entity of the tree, this will be quite often used and should be made
clearer, maybe by an example:

	void** ret, *KEY;
	ret = tsearch( KEY, &root, compare_function );
	if ( *ret == KEY ) operation_on_new_tree_item(*ret,KEY);
	else operation_for_existing_tree_item(*ret,KEY);

bye ingo