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.