DragonFly On-Line Manual Pages

IDR(9)                DragonFly Kernel Developer's Manual               IDR(9)

NAME
     idr, idr_alloc, idr_destroy, idr_find, idr_for_each, idr_get_new,
     idr_get_new_above, idr_init, idr_pre_get, idr_remove, idr_remove_all,
     idr_replace - integer ID management library

SYNOPSIS
     #include <sys/idr.h>

     int
     idr_alloc(struct idr *idp, void *ptr, int start, int end,
         unsigned gfp_mask);

     void
     idr_destroy(struct idr *idp);

     void *
     idr_find(struct idr *idp, int id);

     int
     idr_for_each(struct idr *idp, int (*fn)(int id, void *p, void *data),
         void *data);

     int
     idr_get_new(struct idr *idp, void *ptr, int *id);

     int
     idr_get_new_above(struct idr *idp, void *ptr, int sid, int *id);

     void
     idr_init(struct idr *idp);

     int
     idr_pre_get(struct idr *idp, unsigned gfp_mask);

     void *
     idr_remove(struct idr *idp, int id);

     void
     idr_remove_all(struct idr *idp);

     void *
     idr_replace(struct idr *idp, void *ptr, int id);

DESCRIPTION
     The idr API is a generic facility to manage ID allocations and provides
     the ability to map an ID to a pointer.  It is implemented and expected to
     be compatible with the Linux implementation.

     The idr_init() function initialize an idr handle that will be used by
     other functions of this API.

     The idr_destroy() function frees all resources taken by the specified idr
     handle idp.

     The idr_alloc() function allocates an unused ID in the range specified by
     start (inclusive) and end (exclusive).  If end is <= 0, it is treated as
     one larger than INT_MAX.  It returns the newly allocated ID, -ENOMEM if
     memory allocation failed, or -ENOSPC if no free IDs could be found.  The
     gfp_mask is only present for compatibility with the Linux implementation
     and is unused on DragonFly.

     The idr_find() function returns the data pointer that is mapped with the
     specified id.  A NULL return may indicate that the id is not allocated or
     that the NULL pointer was associated with this ID.

     The idr_for_each() function iterates through all pointers registered with
     the specified idr handle idp and calls the callback function fn() for
     each pointer.  It is not safe to modify the idr tree through the callback
     function.  If the callback function returns a non-zero integer, it stops
     and returns the value.

     The idr_get_new() and idr_get_new_above() functions allocate a new
     integer mapped with the specified pointer ptr.  The new ID will be stored
     in id.  If the tree becomes full, these functions will return -EAGAIN.
     In this case, idr_pre_get() should be called to grow the tree.

     The idr_pre_get() function should be called prior to calling
     idr_get_new() and 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 gfp_mask is only present for compatibility with the
     Linux implementation of this API and is unused on DragonFly.

     The idr_remove() function removes the specified id from the tree,
     returning its pointer.  NULL is returned if the id could not be found.

     The idr_remove_all() function removes all entries in the idr tree idp.

     The idr_replace() function replaces the pointer for the specified id with
     the new pointer ptr.  It returns NULL if the id is not found.  Warning:
     This behavior is different from the Linux API, which returns -ENOENT if
     the id could not be found.

HISTORY
     The idr API first appeared in DragonFly 3.3 as an alternative to the
     FreeBSD unr(9) API.

AUTHORS
     Vishesh Yadav <vishesh3y@gmail.com>,
     Francois Tigeot <ftigeot@wolfpond.org>, and
     Matthew Dillon <dillon@apollo.backplane.com>.

DragonFly 6.5-DEVELOPMENT      January 19, 2026      DragonFly 6.5-DEVELOPMENT