.\"
.\" Copyright (c) 2012 Vishesh Yadav
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd March 16, 2019
.Dt IDR 9
.Os
.Sh NAME
.Nm idr ,
.Nm idr_destroy ,
.Nm idr_find ,
.Nm idr_for_each ,
.Nm idr_get_new ,
.Nm idr_get_new_above ,
.Nm idr_init ,
.Nm idr_pre_get ,
.Nm idr_remove ,
.Nm idr_remove_all ,
.Nm idr_replace
.Nd integer ID management library
.Sh SYNOPSIS
.In sys/idr.h
.Ft void
.Fn idr_destroy "struct idr *idp"
.Ft void *
.Fn idr_find "struct idr *idp" "int id"
.Ft int
.Fn idr_for_each "struct idr *idp" "int (*fn)(int id, void *p, void *data)" "void *data"
.Ft int
.Fn idr_get_new "struct idr *idp" "void *ptr" "int *id"
.Ft int
.Fn idr_get_new_above "struct idr *idp" "void *ptr" "int sid" "int *id"
.Ft void
.Fn idr_init "struct idr *idp"
.Ft int
.Fn idr_pre_get "struct idr *idp" "unsigned gfp_mask"
.Ft void *
.Fn idr_remove "struct idr *idp" "int id"
.Ft void
.Fn idr_remove_all "struct idr *idp"
.Ft void *
.Fn idr_replace "struct idr *idp" "void *ptr" "int id"
.Sh DESCRIPTION
The
.Fn idr_init
function initialize an
.Nm
handle that will be used by other functions of this API.
.Pp
The
.Fn idr_destroy
function frees all resources taken by the specified
.Nm
handle
.Fa idp .
.Pp
The
.Fn idr_find
function returns the data pointer that is mapped with the specified
.Fa id .
.Pp
The
.Fn idr_for_each
function iterates through all pointers registered with the specified
.Nm
handle
.Fa idp
and calls the callback function
.Fn fn
for each pointer.
It is not safe to modify the
.Nm
tree through the callback function.
If the callback function returns a non-zero integer, it stops and returns the
value.
.Pp
The
.Fn idr_get_new
and
.Fn idr_get_new_above
functions allocate a new integer mapped with the specified pointer
.Fa ptr .
The new ID will be stored in
.Fa id .
If the tree becomes full, these functions will return
.Fl Ns Er EAGAIN .
In this case,
.Fn idr_pre_get
should be called to grow the tree.
.Pp
The
.Fn idr_pre_get
function should be called prior to calling
.Fn idr_get_new
and
.Fn idr_get_new_above
and preallocates enough memory for subsequent calls to these functions.
It should be called without any locks held and returns 1 if enough memory
was successfully allocated, otherwise 0.
The
.Fa gfp_mask
is only present for compatibility with the Linux implementation of
this API and is unused on
.Dx .
.Pp
The
.Fn idr_remove
function removes the specified
.Fa id
from the tree, returning its pointer.
NULL is returned if the id could not be found.
.Pp
The
.Fn idr_remove_all
function removes all entries in the
.Nm
tree
.Fa idp .
.Pp
The
.Fn idr_replace
function replaces the pointer for the specified
.Fa id
with the new pointer
.Fa ptr .
It returns
.Dv NULL
if the id is not found.
This behavior is different from the Linux API, which returns ERR_PTR(-ENOENT)
if the id could not be found.