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 avl_create 3AVL ,
132.Xr libavl 3LIB
133