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 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 94value. 95.Pp 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, 107.Fn idr_pre_get 108should be called to grow the tree. 109.Pp 110The 111.Fn idr_init 112and 113.Fn idr_init1 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. 160