1.\" Copyright (c) 2005 Gleb Smirnoff <glebius@FreeBSD.org> 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.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd April 21, 2022 28.Dt UNR 9 29.Os 30.Sh NAME 31.Nm new_unrhdr , 32.Nm clear_unrhdr , 33.Nm delete_unrhdr , 34.Nm alloc_unr , 35.Nm alloc_unr_specific , 36.Nm free_unr 37.Nd "kernel unit number allocator" 38.Sh SYNOPSIS 39.In sys/systm.h 40.Ft "struct unrhdr *" 41.Fn new_unrhdr "int low" "int high" "struct mtx *mutex" 42.Ft void 43.Fn clear_unrhdr "struct unrhdr *uh" 44.Ft void 45.Fn delete_unrhdr "struct unrhdr *uh" 46.Ft int 47.Fn alloc_unr "struct unrhdr *uh" 48.Ft int 49.Fn alloc_unrl "struct unrhdr *uh" 50.Ft int 51.Fn alloc_unr_specific "struct unrhdr *uh" "u_int item" 52.Ft void 53.Fn free_unr "struct unrhdr *uh" "u_int item" 54.Sh DESCRIPTION 55The kernel unit number allocator is a generic facility, which allows to allocate 56unit numbers within a specified range. 57.Bl -tag -width indent 58.It Fn new_unrhdr low high mutex 59Initialize a new unit number allocator entity. 60The 61.Fa low 62and 63.Fa high 64arguments 65specify minimum and maximum number of unit numbers. 66There is no cost associated with the range of unit numbers, so unless the resource 67really is finite, 68.Dv INT_MAX 69can be used. 70If 71.Fa mutex 72is not 73.Dv NULL , 74it is used for locking when allocating and freeing units. 75If the passed value is the token 76.Va UNR_NO_MTX , 77then no locking is applied internally. 78Otherwise, internal mutex is used. 79.It Fn clear_unrhdr uh 80Clear all units from the specified unit number allocator entity. 81This function resets the entity as if it were just initialized with 82.Fn new_unrhdr . 83.It Fn delete_unrhdr uh 84Delete specified unit number allocator entity. 85This function frees the memory associated with the entity, it does not free 86any units. 87To free all units use 88.Fn clear_unrhdr . 89.It Fn alloc_unr uh 90Return a new unit number. 91The lowest free number is always allocated. 92This function does not allocate memory and never sleeps, however it may 93block on a mutex. 94If no free unit numbers are left, 95.Li \-1 96is returned. 97.It Fn alloc_unrl uh 98Same as 99.Fn alloc_unr 100except that mutex is assumed to be already locked and thus is not used. 101.It Fn alloc_unr_specific uh item 102Allocate a specific unit number. 103This function allocates memory and thus may sleep. 104The allocated unit number is returned on success. 105If the specified number is already allocated or out of the range, 106.Li \-1 107is returned. 108.It Fn free_unr uh item 109Free a previously allocated unit number. 110This function may require allocating memory, and thus it can sleep. 111There is no pre-locked variant. 112.El 113.Sh CODE REFERENCES 114The above functions are implemented in 115.Pa sys/kern/subr_unit.c . 116.Sh HISTORY 117Kernel unit number allocator first appeared in 118.Fx 6.0 . 119.Sh AUTHORS 120.An -nosplit 121Kernel unit number allocator was written by 122.An Poul-Henning Kamp . 123This manpage was written by 124.An Gleb Smirnoff . 125