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 .