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_pre_get ,
  39 .Nm idr_remove ,
  40 .Nm idr_remove_all ,
  41 .Nm idr_replace
  42 .Nd integer ID management library
  43 .Sh SYNOPSIS
  44 .In sys/idr.h
  45 .Ft void
  46 .Fn idr_destroy "struct idr *idp"
  47 .Ft void *
  48 .Fn idr_find "struct idr *idp" "int id"
  49 .Ft int
  50 .Fn idr_for_each "struct idr *idp" "int (*fn)(int id, void *p, void *data)" "void *data"
  51 .Ft int
  52 .Fn idr_get_new "struct idr *idp" "void *ptr" "int *id"
  53 .Ft int
  54 .Fn idr_get_new_above "struct idr *idp" "void *ptr" "int sid" "int *id"
  55 .Ft void
  56 .Fn idr_init "struct idr *idp"
  57 .Ft int
  58 .Fn idr_pre_get "struct idr *idp" "unsigned gfp_mask"
  59 .Ft void
  60 .Fn idr_remove "struct idr *idp" "int id"
  61 .Ft void
  62 .Fn idr_remove_all "struct idr *idp"
  63 .Ft void *
  64 .Fn idr_replace "struct idr *idp" "void *ptr" "int id"
  65 .Sh DESCRIPTION
  66 The
  67 .Fn idr_destroy
  68 function frees all resources taken by the specified
  69 .Nm
  70 handle
  71 .Fa idp .
  72 .Pp
  73 The
  74 .Fn idr_find
  75 function returns the data pointer that is mapped with the specified
  76 .Fa id .
  77 .Pp
  78 The
  79 .Fn idr_for_each
  80 function iterates through all pointers registered with the specified
  81 .Nm
  82 handle
  83 .Fa idp
  84 and calls the callback function
  85 .Fn fn
  86 for each pointer.
  87 It is not safe to modify the
  88 .Nm
  89 tree through the callback function.
  90 If the callback function returns a non-zero integer, it stops and returns the
  91 value.
  92 .Pp
  93 The
  94 .Fn idr_get_new
  95 and
  96 .Fn idr_get_new_above
  97 functions allocate a new integer mapped with the specified pointer
  98 .Fa ptr .
  99 The new ID will be stored in
 100 .Fa id .
 101 If the tree becomes full, these functions will return
 102 .Er -EAGAIN .
 103 In this case,
 104 .Fn idr_pre_get
 105 should be called to grow the tree.
 106 .Pp
 107 The
 108 .Fn idr_init
 109 function initialize an
 110 .Nm
 111 handle that will be used by other functions of the API.
 112 The
 113 .Fn idr_pre_get
 114 function should be called prior to calling the
 115 .Fn idr_get_new*
 116 functions.
 117 It preallocates enough memory for subsequent calls to
 118 .Fn idr_get_new*
 119 functions.
 120 This function should be called without any locks held.
 121 It returns 0 if enough memory couldn't be allocated, otherwise 1.
 122 The
 123 .Sq Va gfp_mask
 124 parameter is only present for compatibility with the Linux implementation of
 125 this API and is unused on
 126 .Dx .
 127 .
 128 .Pp
 129 The
 130 .Fn idr_remove
 131 function removes the specified
 132 .Fa id
 133 from the tree.
 134 .Pp
 135 The
 136 .Fn idr_remove_all
 137 function removes all entries in the
 138 .Nm
 139 tree
 140 .Fa idp .
 141 .Pp
 142 The
 143 .Fn idr_replace
 144 function replaces the pointer for the specified
 145 .Fa id
 146 with the new pointer
 147 .Fa ptr .
 148 It returns
 149 .Dv NULL
 150 if the pointer is not found.
 151 This behavior is different from the Linux API.