idr.9: Clean up a bit.
[dragonfly.git] / share / man / man9 / idr.9
1 .\" Copyright (c) 2012 Vishesh Yadav
2 .\" All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\"    notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\"    notice, this list of conditions and the following disclaimer in the
11 .\"    documentation and/or other materials provided with the distribution.
12 .\" 3. The name of the author may not be used to endorse or promote products
13 .\"    derived from this software without specific prior written permission.
14 .\"
15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
18 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25 .\"
26 .\"
27 .Dd October 23, 2012
28 .Dt IDR 9
29 .Os
30 .Sh NAME
31 .Nm idr ,
32 .Nm idr_destroy ,
33 .Nm idr_find ,
34 .Nm idr_for_each ,
35 .Nm idr_get_new ,
36 .Nm idr_get_new_above ,
37 .Nm idr_init ,
38 .Nm idr_init1 ,
39 .Nm idr_pre_get ,
40 .Nm idr_remove ,
41 .Nm idr_remove_all ,
42 .Nm idr_replace
43 .Nd integer ID management library
44 .Sh SYNOPSIS
45 .In sys/idr.h
46 .Ft void
47 .Fn idr_destroy "struct idr *idp"
48 .Ft void *
49 .Fn idr_find "struct idr *idp" "int id"
50 .Ft int
51 .Fn idr_for_each "struct idr *idp" "int (*fn)(int id, void *p, void *data)" "void *data"
52 .Ft int
53 .Fn idr_get_new "struct idr *idp" "void *ptr" "int *id"
54 .Ft int
55 .Fn idr_get_new_above "struct idr *idp" "void *ptr" "int sid" "int *id"
56 .Ft void
57 .Fn idr_init "struct idr *idp"
58 .Ft void
59 .Fn idr_init1 "struct idr *idp" "int size"
60 .Ft int
61 .Fn idr_pre_get "struct idr *idp"
62 .Ft void
63 .Fn idr_remove "struct idr *idp" "int id"
64 .Ft void
65 .Fn idr_remove_all "struct idr *idp"
66 .Ft void *
67 .Fn idr_replace "struct idr *idp" "void *ptr" "int id"
68 .Sh DESCRIPTION
69 The
70 .Fn idr_destroy
71 function frees all resources taken by the specified
72 .Nm
73 handle
74 .Fa idp .
75 .Pp
76 The
77 .Fn idr_find
78 function returns the data pointer that is mapped with the specified
79 .Fa id .
80 .Pp
81 The
82 .Fn idr_for_each
83 function iterates through all pointers registered with the specified
84 .Nm
85 handle
86 .Fa idp
87 and calls the callback function
88 .Fn fn
89 for each pointer.
90 It is not safe to modify the
91 .Nm
92 tree through the callback function.
93 If the callback function returns a non-zero integer, it stops and returns the
94 value.
95 .Pp
96 The
97 .Fn idr_get_new
98 and
99 .Fn idr_get_new_above
100 functions allocate a new integer mapped with the specified pointer
101 .Fa ptr .
102 The new ID will be stored in
103 .Fa id .
104 If the tree becomes full, the functions function will return
105 .Er EAGAIN .
106 In this case,
107 .Fn idr_pre_get
108 should be called to grow the tree.
109 .Pp
110 The
111 .Fn idr_init
112 and
113 .Fn idr_init1
114 functions initialize an
115 .Nm
116 handle that will be used by other functions of the API.
117 .Fn idr_init
118 initializes a tree with a hard coded default initial capacity (32).
119 .Fn idr_init1
120 takes additional parameter
121 .Fa size
122 to set the initial capacity manually.
123 The
124 .Fn idr_pre_get
125 function should be called prior to calling the
126 .Fn idr_get_new*
127 functions.
128 It preallocates enough memory for subsequent calls to
129 .Fn idr_get_new*
130 functions.
131 This function should be called without any locks held.
132 It returns 0 if enough memory couldn't be allocated, otherwise 1.
133 This function lacks the
134 .Sq Vt gfp_t Va gfp_mask
135 parameter that is found in Linux version of this API.
136 .Pp
137 The
138 .Fn idr_remove
139 function removes the specified
140 .Fa id
141 from the tree.
142 .Pp
143 The
144 .Fn idr_remove_all
145 function removes all entries in the
146 .Nm
147 tree
148 .Fa idp .
149 .Pp
150 The
151 .Fn idr_replace
152 function replaces the pointer for the specified
153 .Fa id
154 with the new pointer
155 .Fa ptr .
156 It returns
157 .Dv NULL
158 if the pointer is not found.
159 This behavior is different from the Linux API.