idr.9: Clean up a bit.
[dragonfly.git] / share / man / man9 / idr.9
CommitLineData
181ede86
VY
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.\"
f5f75637 27.Dd October 23, 2012
181ede86
VY
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
f5f75637 43.Nd integer ID management library
181ede86
VY
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"
181ede86 68.Sh DESCRIPTION
f5f75637
SW
69The
70.Fn idr_destroy
71function frees all resources taken by the specified
72.Nm
73handle
74.Fa idp .
75.Pp
76The
77.Fn idr_find
78function returns the data pointer that is mapped with the specified
79.Fa id .
80.Pp
81The
82.Fn idr_for_each
83function iterates through all pointers registered with the specified
84.Nm
85handle
86.Fa idp
87and calls the callback function
88.Fn fn
89for each pointer.
90It is not safe to modify the
91.Nm
92tree through the callback function.
93If the callback function returns a non-zero integer, it stops and returns the
181ede86 94value.
181ede86 95.Pp
f5f75637
SW
96The
97.Fn idr_get_new
98and
99.Fn idr_get_new_above
100functions allocate a new integer mapped with the specified pointer
101.Fa ptr .
102The new ID will be stored in
103.Fa id .
104If the tree becomes full, the functions function will return
105.Er EAGAIN .
106In this case,
181ede86
VY
107.Fn idr_pre_get
108should be called to grow the tree.
181ede86 109.Pp
f5f75637 110The
181ede86 111.Fn idr_init
f5f75637 112and
181ede86 113.Fn idr_init1
f5f75637
SW
114functions initialize an
115.Nm
116handle that will be used by other functions of the API.
117.Fn idr_init
118initializes a tree with a hard coded default initial capacity (32).
119.Fn idr_init1
120takes additional parameter
121.Fa size
122to set the initial capacity manually.
123The
124.Fn idr_pre_get
125function should be called prior to calling the
126.Fn idr_get_new*
127functions.
128It preallocates enough memory for subsequent calls to
129.Fn idr_get_new*
130functions.
131This function should be called without any locks held.
132It returns 0 if enough memory couldn't be allocated, otherwise 1.
133This function lacks the
134.Sq Vt gfp_t Va gfp_mask
135parameter that is found in Linux version of this API.
136.Pp
137The
138.Fn idr_remove
139function removes the specified
140.Fa id
141from the tree.
142.Pp
143The
144.Fn idr_remove_all
145function removes all entries in the
146.Nm
147tree
148.Fa idp .
149.Pp
150The
151.Fn idr_replace
152function replaces the pointer for the specified
153.Fa id
154with the new pointer
155.Fa ptr .
156It returns
157.Dv NULL
158if the pointer is not found.
159This behavior is different from the Linux API.