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 October 4, 2017 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. 75Otherwise, internal mutex is used. 76.It Fn clear_unrhdr uh 77Clear all units from the specified unit number allocator entity. 78This function resets the entity as if it were just initialized with 79.Fn new_unrhdr . 80.It Fn delete_unrhdr uh 81Delete specified unit number allocator entity. 82This function frees the memory associated with the entity, it does not free 83any units. 84To free all units use 85.Fn clear_unrhdr . 86.It Fn alloc_unr uh 87Return a new unit number. 88The lowest free number is always allocated. 89This function does not allocate memory and never sleeps, however it may 90block on a mutex. 91If no free unit numbers are left, 92.Li \-1 93is returned. 94.It Fn alloc_unrl uh 95Same as 96.Fn alloc_unr 97except that mutex is assumed to be already locked and thus is not used. 98.It Fn alloc_unr_specific uh item 99Allocate a specific unit number. 100This function allocates memory and thus may sleep. 101The allocated unit number is returned on success. 102If the specified number is already allocated or out of the range, 103.Li \-1 104is returned. 105.It Fn free_unr uh item 106Free a previously allocated unit number. 107This function may require allocating memory, and thus it can sleep. 108There is no pre-locked variant. 109.El 110.Sh CODE REFERENCES 111The above functions are implemented in 112.Pa sys/kern/subr_unit.c . 113.Sh HISTORY 114Kernel unit number allocator first appeared in 115.Fx 6.0 . 116.Sh AUTHORS 117.An -nosplit 118Kernel unit number allocator was written by 119.An Poul-Henning Kamp . 120This manpage was written by 121.An Gleb Smirnoff . 122