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 -ENOENT if the id could not be found.

FILES
The above functions are implemented in sys/libkern/linux_idr.c.

SEE ALSO
unr(9)

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>, François Tigeot <ftigeot@wolfpond.org>, and Matthew Dillon <dillon@apollo.backplane.com>.