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. 79See the examples section in 80.Xr libavl 3LIB 81for more information on using this 82interface. 83.Sh RETURN VALUES 84The 85.Fn avl_first 86function returns a pointer to the first entry in the AVL tree 87.Fa tree 88or 89.Sy NULL 90if the AVL tree is empty. 91.Pp 92The 93.Fn avl_last 94function returns a pointer to the last entry in the AVL tree 95.Fa tree 96or 97.Sy NULL 98if the AVL tree is empty. 99.Pp 100The 101.Fn AVL_NEXT 102macro returns a pointer to the object in the tree that follows 103.Fa node . 104If 105.Fa node 106is the last entry in the tree, 107.Sy NULL 108is returned instead. 109.Pp 110The 111.Fn AVL_PREV 112macro returns a pointer to the object in the tree that precedes 113.Fa node . 114If 115.Fa node 116is the first entry in the tree, 117.Sy NULL 118is returned instead. 119.Sh EXAMPLES 120See the 121.Sy EXAMPLES 122section in 123.Xr libavl 3LIB . 124.Sh INTERFACE STABILITY 125.Sy Committed 126.Sh MT-Level 127See 128.Sx Locking 129in 130.Xr libavl 3LIB . 131.Sh SEE ALSO 132.Xr avl_create 3AVL , 133.Xr libavl 3LIB 134