1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2015 Joyent, Inc. 13.\" 14.Dd May 07, 2015 15.Dt AVL_FIRST 3AVL 16.Os 17.Sh NAME 18.Nm avl_first , 19.Nm AVL_NEXT , 20.Nm AVL_PREV , 21.Nm avl_last 22.Nd get the first, next, previous, and last entries from an AVL tree 23.Sh SYNOPSIS 24.Lb libavl 25.In sys/avl.h 26.Ft void * 27.Fo avl_first 28.Fa "avl_tree_t *tree" 29.Fc 30.Ft void * 31.Fo avl_last 32.Fa "avl_tree_t *tree" 33.Fc 34.Ft void * 35.Fo AVL_NEXT 36.Fa "avl_tree_t *tree" 37.Fa "void *node" 38.Fc 39.Ft void * 40.Fo AVL_PREV 41.Fa "avl_tree_t *tree" 42.Fa "void *node" 43.Fc 44.Sh DESCRIPTION 45The 46.Fn avl_first 47and 48.Fn avl_last 49respectively return the first and last entry in the tree specified by 50.Fa tree . 51Order in the tree is determined by the comparison function that was 52specified at the time the tree was created with 53.Xr avl_create 3AVL . 54If 55.Fa tree 56is empty, then 57.Fn avl_first 58and 59.Fn avl_last 60return 61.Sy NULL . 62.Pp 63The 64.Fn AVL_NEXT 65and 66.Fn AVL_PREV 67functions are macros that may be used to obtain the next and previous 68entry following 69.Fa node 70in the AVL tree 71.Fa tree . 72If there is no next or previous node, for example, if one was at the 73beginning or end of the tree, then 74.Sy NULL 75is returned. 76.Pp 77These constructs are generally used as part of loops to iterate the 78tree. See the examples section in 79.Xr libavl 3LIB 80for more information on using this 81interface. 82.Sh RETURN VALUES 83The 84.Fn avl_first 85function returns a pointer to the first entry in the AVL tree 86.Fa tree 87or 88.Sy NULL 89if the AVL tree is empty. 90.Pp 91The 92.Fn avl_last 93function returns a pointer to the last entry in the AVL tree 94.Fa tree 95or 96.Sy NULL 97if the AVL tree is empty. 98.Pp 99The 100.Fn AVL_NEXT 101macro returns a pointer to the object in the tree that follows 102.Fa node . 103If 104.Fa node 105is the last entry in the tree, 106.Sy NULL 107is returned instead. 108.Pp 109The 110.Fn AVL_PREV 111macro returns a pointer to the object in the tree that precedes 112.Fa node . 113If 114.Fa node 115is the first entry in the tree, 116.Sy NULL 117is returned instead. 118.Sh EXAMPLES 119See the 120.Sy EXAMPLES 121section in 122.Xr libavl 3LIB . 123.Sh INTERFACE STABILITY 124.Sy Committed 125.Sh MT-Level 126See 127.Sx Locking 128in 129.Xr libavl 3LIB . 130.Sh SEE ALSO 131.Xr libavl 3LIB , 132.Xr avl_create 3AVL 133