TDELETE(3)                 POSIX Programmer's Manual                TDELETE(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.


NNAAMMEE
       tdelete, tfind, tsearch, twalk -- manage a binary search tree

SSYYNNOOPPSSIISS
       #include <search.h>

       void *tdelete(const void *restrict _k_e_y, void **restrict _r_o_o_t_p,
           int(*_c_o_m_p_a_r)(const void *, const void *));
       void *tfind(const void *_k_e_y, void *const *_r_o_o_t_p,
           int(*_c_o_m_p_a_r)(const void *, const void *));
       void *tsearch(const void *_k_e_y, void **_r_o_o_t_p,
           int (*_c_o_m_p_a_r)(const void *, const void *));
       void twalk(const void *_r_o_o_t,
           void (*_a_c_t_i_o_n)(const void *, VISIT, int));

DDEESSCCRRIIPPTTIIOONN
       The _t_d_e_l_e_t_e(), _t_f_i_n_d(), _t_s_e_a_r_c_h(), and _t_w_a_l_k() functions manipulate
       binary search trees. Comparisons are made with a user-supplied routine,
       the address of which is passed as the _c_o_m_p_a_r argument. This routine is
       called with two arguments, which are the pointers to the elements being
       compared. The application shall ensure that the user-supplied routine
       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.

       The _t_s_e_a_r_c_h() function shall build and access the tree. The _k_e_y
       argument is a pointer to an element to be accessed or stored. If there
       is a node in the tree whose element is equal to the value pointed to by
       _k_e_y, a pointer to this found node shall be returned. Otherwise, the
       value pointed to by _k_e_y shall be inserted (that is, a new node is
       created and the value of _k_e_y is copied to this node), and a pointer to
       this node returned. Only pointers are copied, so the application shall
       ensure that the calling routine stores the data. The _r_o_o_t_p argument
       points to a variable that points to the root node of the tree. A null
       pointer value for the variable pointed to by _r_o_o_t_p denotes an empty
       tree; in this case, the variable shall be set to point to the node
       which shall be at the root of the new tree.

       Like _t_s_e_a_r_c_h(), _t_f_i_n_d() shall search for a node in the tree, returning
       a pointer to it if found.  However, if it is not found, _t_f_i_n_d() shall
       return a null pointer. The arguments for _t_f_i_n_d() are the same as for
       _t_s_e_a_r_c_h().

       The _t_d_e_l_e_t_e() function shall delete a node from a binary search tree.
       The arguments are the same as for _t_s_e_a_r_c_h().  The variable pointed to
       by _r_o_o_t_p shall be changed if the deleted node was the root of the tree.
       The _t_d_e_l_e_t_e() function shall return a pointer to the parent of the
       deleted node, or an unspecified non-null pointer if the deleted node
       was the root node, or a null pointer if the node is not found.

       If _t_s_e_a_r_c_h() adds an element to a tree, or _t_d_e_l_e_t_e() successfully
       deletes an element from a tree, the concurrent use of that tree in
       another thread, or use of pointers produced by a previous call to
       _t_f_i_n_d() or _t_s_e_a_r_c_h(), produces undefined results.

       The _t_w_a_l_k() function shall traverse a binary search tree. The _r_o_o_t
       argument is a pointer to the root node of the tree to be traversed.
       (Any node in a tree may be used as the root for a walk below that
       node.) The argument _a_c_t_i_o_n is the name of a routine to be invoked at
       each node. This routine is, in turn, called with three arguments. The
       first argument shall be the address of the node being visited. The
       structure pointed to by this argument is unspecified and shall not be
       modified by the application, but it shall be possible to cast a
       pointer-to-node into a pointer-to-pointer-to-element to access the
       element stored in the node.  The second argument shall be a value from
       an enumeration data type:

           ttyyppeeddeeff eennuumm {{ pprreeoorrddeerr,, ppoossttoorrddeerr,, eennddoorrddeerr,, lleeaaff }} VVIISSIITT;;

       (defined in _<_s_e_a_r_c_h_._h_>), depending on whether this is the first,
       second, or third time that the node is visited (during a depth-first,
       left-to-right traversal of the tree), or whether the node is a leaf.
       The third argument shall be the level of the node in the tree, with the
       root being level 0.

       If the calling function alters the pointer to the root, the result is
       undefined.

       If the functions pointed to by _a_c_t_i_o_n or _c_o_m_p_a_r (for any of these
       binary search functions) change the tree, the results are undefined.

       These functions are thread-safe only as long as multiple threads do not
       access the same tree.

RREETTUURRNN VVAALLUUEE
       If the node is found, both _t_s_e_a_r_c_h() and _t_f_i_n_d() shall return a pointer
       to it. If not, _t_f_i_n_d() shall return a null pointer, and _t_s_e_a_r_c_h() shall
       return a pointer to the inserted item.

       A null pointer shall be returned by _t_s_e_a_r_c_h() if there is not enough
       space available to create a new node.

       A null pointer shall be returned by _t_d_e_l_e_t_e(), _t_f_i_n_d(), and _t_s_e_a_r_c_h()
       if _r_o_o_t_p is a null pointer on entry.

       The _t_d_e_l_e_t_e() function shall return a pointer to the parent of the
       deleted node, or an unspecified non-null pointer if the deleted node
       was the root node, or a null pointer if the node is not found.

       The _t_w_a_l_k() function shall not return a value.

EERRRROORRSS
       No errors are defined.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       The following code reads in strings and stores structures containing a
       pointer to each string and a count of its length. It then walks the
       tree, printing out the stored strings and their lengths in alphabetical
       order.

           ##iinncclluuddee <<sseeaarrcchh..hh>>
           ##iinncclluuddee <<ssttrriinngg..hh>>
           ##iinncclluuddee <<ssttddiioo..hh>>

           #define STRSZ    10000
           #define NODSZ    500

           struct node {      /* Pointers to these are stored in the tree. */
               char    *string;
               int     length;
           };

           char   string_space[STRSZ];  /* Space to store strings. */
           struct node nodes[NODSZ];    /* Nodes to store. */
           void  *root = NULL;          /* This points to the root. */

           int main(int argc, char *argv[])
           {
               char   *strptr = string_space;
               struct node    *nodeptr = nodes;
               void   print_node(const void *, VISIT, int);
               int    i = 0, node_compare(const void *, const void *);

               while (gets(strptr) != NULL && i++ < NODSZ)  {
                   /* Set node. */
                   nodeptr->string = strptr;
                   nodeptr->length = strlen(strptr);
                   /* Put node into the tree. */
                   (void) tsearch((void *)nodeptr, (void **)&root,
                       node_compare);
                   /* Adjust pointers, so we do not overwrite tree. */
                   strptr += nodeptr->length + 1;
                   nodeptr++;
               }
               twalk(root, print_node);
               return 0;
           }

           /*
            *  This routine compares two nodes, based on an
            *  alphabetical ordering of the string field.
            */
           int
           node_compare(const void *node1, const void *node2)
           {
               return strcmp(((const struct node *) node1)->string,
                   ((const struct node *) node2)->string);
           }

           /*
            *  This routine prints out a node, the second time
            *  twalk encounters it or if it is a leaf.
            */
           void
           print_node(const void *ptr, VISIT order, int level)
           {
               const struct node *p = *(const struct node **) ptr;

               if (order == postorder || order == leaf)  {
                   (void) printf("string = %s,  length = %d\n",
                       p->string, p->length);
               }
           }

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       The _r_o_o_t argument to _t_w_a_l_k() is one level of indirection less than the
       _r_o_o_t_p arguments to _t_d_e_l_e_t_e() and _t_s_e_a_r_c_h().

       There are two nomenclatures used to refer to the order in which tree
       nodes are visited. The _t_s_e_a_r_c_h() function uses pprreeoorrddeerr, ppoossttoorrddeerr, and
       eennddoorrddeerr to refer respectively to visiting a node before any of its
       children, after its left child and before its right, and after both its
       children. The alternative nomenclature uses pprreeoorrddeerr, iinnoorrddeerr, and
       ppoossttoorrddeerr to refer to the same visits, which could result in some
       confusion over the meaning of ppoossttoorrddeerr.

       Since the return value of _t_d_e_l_e_t_e() is an unspecified non-null pointer
       in the case that the root of the tree has been deleted, applications
       should only use the return value of _t_d_e_l_e_t_e() as indication of success
       or failure and should not assume it can be dereferenced. Some
       implementations in this case will return a pointer to the new root of
       the tree (or to an empty tree if the deleted root node was the only
       node in the tree); other implementations return arbitrary non-null
       pointers.

RRAATTIIOONNAALLEE
       None.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _h_c_r_e_a_t_e(), _l_s_e_a_r_c_h()

       The Base Definitions volume of POSIX.1-2008, <<sseeaarrcchh..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be obtained online
       at http://www.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2013                           TDELETE(3)
