share/man/man9/idr.9

   1 .\"
   2 .\" Copyright (c) 2012 Vishesh Yadav
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. The name of the author may not be used to endorse or promote products
  14 .\"    derived from this software without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  17 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  18 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  19 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  20 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  21 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  22 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  23 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  25 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26 .\"
  27 .Dd March 21, 2018
  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_init
  68 function initialize an
  69 .Nm
  70 handle that will be used by other functions of this API.
  71 .Pp
  72 The
  73 .Fn idr_destroy
  74 function frees all resources taken by the specified
  75 .Nm
  76 handle
  77 .Fa idp .
  78 .Pp
  79 The
  80 .Fn idr_find
  81 function returns the data pointer that is mapped with the specified
  82 .Fa id .
  83 .Pp
  84 The
  85 .Fn idr_for_each
  86 function iterates through all pointers registered with the specified
  87 .Nm
  88 handle
  89 .Fa idp
  90 and calls the callback function
  91 .Fn fn
  92 for each pointer.
  93 It is not safe to modify the
  94 .Nm
  95 tree through the callback function.
  96 If the callback function returns a non-zero integer, it stops and returns the
  97 value.
  98 .Pp
  99 The
 100 .Fn idr_get_new
 101 and
 102 .Fn idr_get_new_above
 103 functions allocate a new integer mapped with the specified pointer
 104 .Fa ptr .
 105 The new ID will be stored in
 106 .Fa id .
 107 If the tree becomes full, these functions will return
 108 .Fl Ns Er EAGAIN .
 109 In this case,
 110 .Fn idr_pre_get
 111 should be called to grow the tree.
 112 .Pp
 113 The
 114 .Fn idr_pre_get
 115 function should be called prior to calling
 116 .Fn idr_get_new
 117 and
 118 .Fn idr_get_new_above
 119 and preallocates enough memory for subsequent calls to these functions.
 120 It should be called without any locks held and returns 1 if enough memory
 121 was successfully allocated, otherwise 0.
 122 The
 123 .Fa gfp_mask
 124 is only present for compatibility with the Linux implementation of
 125 this API and is unused on
 126 .Dx .
 127 .Pp
 128 The
 129 .Fn idr_remove
 130 function removes the specified
 131 .Fa id
 132 from the tree.
 133 .Pp
 134 The
 135 .Fn idr_remove_all
 136 function removes all entries in the
 137 .Nm
 138 tree
 139 .Fa idp .
 140 .Pp
 141 The
 142 .Fn idr_replace
 143 function replaces the pointer for the specified
 144 .Fa id
 145 with the new pointer
 146 .Fa ptr .
 147 It returns
 148 .Dv NULL
 149 if the pointer is not found.
 150 This behavior is different from the Linux API.