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 July 5, 2010 28.Dt UNR 9 29.Os 30.Sh NAME 31.Nm new_unrhdr , 32.Nm delete_unrhdr , 33.Nm alloc_unr , 34.Nm alloc_unr_specific , 35.Nm free_unr 36.Nd "kernel unit number allocator" 37.Sh SYNOPSIS 38.In sys/systm.h 39.Ft "struct unrhdr *" 40.Fn new_unrhdr "int low" "int high" "struct mtx *mutex" 41.Ft void 42.Fn delete_unrhdr "struct unrhdr *uh" 43.Ft int 44.Fn alloc_unr "struct unrhdr *uh" 45.Ft int 46.Fn alloc_unrl "struct unrhdr *uh" 47.Ft int 48.Fn alloc_unr_specific "struct unrhdr *uh" "u_int item" 49.Ft void 50.Fn free_unr "struct unrhdr *uh" "u_int item" 51.Sh DESCRIPTION 52The kernel unit number allocator is a generic facility, which allows to allocate 53unit numbers within a specified range. 54.Bl -tag -width indent 55.It Fn new_unrhdr low high mutex 56Initialize a new unit number allocator entity. 57The 58.Fa low 59and 60.Fa high 61arguments 62specify minimum and maximum number of unit numbers. 63There is no cost associated with the range of unit numbers, so unless the resource 64really is finite, 65.Dv INT_MAX 66can be used. 67If 68.Fa mutex 69is not 70.Dv NULL , 71it is used for locking when allocating and freeing units. 72Otherwise, internal mutex is used. 73.It Fn delete_unrhdr uh 74Destroy specified unit number allocator entity. 75.It Fn alloc_unr uh 76Return a new unit number. 77The lowest free number is always allocated. 78This function does not allocate memory and never sleeps, however it may 79block on a mutex. 80If no free unit numbers are left, 81.Li \-1 82is returned. 83.It Fn alloc_unrl uh 84Same as 85.Fn alloc_unr 86except that mutex is assumed to be already locked and thus is not used. 87.It Fn alloc_unr_specific uh item 88Allocate a specific unit number. 89This function allocates memory and thus may sleep. 90The allocated unit number is returned on success. 91If the specified number is already allocated or out of the range, 92.Li \-1 93is returned. 94.It Fn free_unr uh item 95Free a previously allocated unit number. 96This function may require allocating memory, and thus it can sleep. 97There is no pre-locked variant. 98.El 99.Sh CODE REFERENCES 100The above functions are implemented in 101.Pa sys/kern/subr_unit.c . 102.Sh HISTORY 103Kernel unit number allocator first appeared in 104.Fx 6.0 . 105.Sh AUTHORS 106.An -nosplit 107Kernel unit number allocator was written by 108.An Poul-Henning Kamp . 109This manpage was written by 110.An Gleb Smirnoff . 111