01dc9797eef753787eda617db2da9f52899c1513
[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 August 15, 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 .
69 .Sh DESCRIPTION
70 .Pp
71 .Fn idr_destroy "struct idr *idp"
72 .Pp
73 Free all resources taken by given idr handle.
74 .
75 .Pp
76 .Fn idr_find "struct idr *idp" "int id"
77 .Pp
78 Return data pointer mapped with given id.
79 .
80 .Pp
81 .Fn idr_for_each "struct idr *idp" "int (*fn)(int id, void *p, void *data)" "void *data"
82 .Pp
83 Iterate through all pointers registered with given idr handle and call the
84 callback function 'fn' for each pointer. It is not safe to modify the idr tree
85 through the callback function.
86 .Pp
87 If the callback function returns a non-zero integer, we stop and return the
88 value.
89 .
90 .Pp
91 .Fn idr_get_new "struct idr *idp" "void *ptr" "int *id",
92 .Fn idr_get_new_above "struct idr *idp" "void *ptr" "int sid" "int *id"
93 .Pp
94 Allocates a new integer mapped with pointer 'ptr'. The new id will be stored
95 in 'id'. If the tree get full, function will return EAGAIN.
96 .Fn idr_pre_get
97 should be called to grow the tree.
98 .
99 .Pp
100 .Fn idr_init "struct idr *idp",
101 .Fn idr_init1 "struct idr *idp" "int size"
102 .Pp
103 Initialize idr handle that will be used by other functions of the API.
104 .Fn idr_init
105 initializes tree with hard coded default initial capacity (32).
106 .Fn idr_init1
107 takes additional parameter 'size' to set the initial capacity manually.
108 .
109 .Pp
110 .Fn idr_pre_get "struct idr *idp"
111 .Pp
112 This function should be called prior to calling the idr_get_new* functions. It
113 preallocates enough memory for subsequent calls to idr_get_new* functions. This 
114 function should be called without any locks held.
115 .Pp
116 This function returns 0 if enough memory couldn't be allocated, otherwise 1.
117 .Pp
118 This function lacks 'gfp_t gfp_mask' parameter that is found in Linux version of
119 this API.
120 .
121 .Pp
122 .Fn idr_remove "struct idr *idp" "int id",
123 .Pp
124 Remove the given id from tree.
125 .
126 .Pp
127 .Fn idr_remove_all "struct idr *idp"
128 .Pp
129 Remove all entries in the idr tree.
130 .
131 .Pp
132 .Fn idr_replace "struct idr *idp" "void *ptr" "int id"
133 .Pp
134 Replace pointer for given id with new pointer.
135 .Pp
136 NULL is returned if pointer is not found. This behavior is different from the
137 Linux API.
138 .