Manpage for unit allocator functions.

Reviewed by:	phk

share/man/man9/Makefile

@@ -4,6 +4,7 @@ MAN=	accept_filter.9 \
 	accf_data.9 \
 	accf_http.9 \
 	acl.9 \
+	alloc_unr.9 \
 	alq.9 \
 	altq.9 \
 	atomic.9 \
@@ -334,7 +335,11 @@ MAN=	accept_filter.9 \
 	zero_copy.9 \
 	zone.9
 
-MLINKS=	alq.9 ALQ.9 \
+MLINKS=	alloc_unr.9 alloc_unrl.9 \
+	alloc_unr.9 delete_unrhdr.9 \
+	alloc_unr.9 free_unr.9 \
+	alloc_unr.9 new_unrhdr.9
+MLINKS+=alq.9 ALQ.9 \
 	alq.9 alq_close.9 \
 	alq.9 alq_flush.9 \
 	alq.9 alq_get.9 \

share/man/man9/alloc_unr.9

@@ -0,0 +1,98 @@
+.\" Copyright (c) 2005 Gleb Smirnoff <glebius@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd March 23, 2005
+.Dt ALLOC_UNR 9
+.Os
+.Sh NAME
+.Nm new_unrhdr ,
+.Nm delete_unrhdr ,
+.Nm alloc_unr ,
+.Nm free_unr
+.Nd "kernel unit number allocator"
+.Sh SYNOPSIS
+.In sys/systm.h
+.Ft "struct unrhdr *"
+.Fn new_unrhdr "int low" "int high" "struct mtx *mutex"
+.Ft void
+.Fn delete_unrhdr "struct unrhdr *uh"
+.Ft int
+.Fn alloc_unr "struct unrhdr *uh"
+.Ft int
+.Fn alloc_unrl "struct unrhdr *uh"
+.Ft void
+.Fn free_unr "struct unrhdr *uh" "u_int item"
+.Sh DESCRIPTION
+The kernel unit number allocator is a generic facility, which allows to allocate
+unit numbers within a specified range.
+.Bl -ohang
+.It Fn new_unrhdr low high mutex
+Initialize a new unit number allocator entity.
+.Fa low
+and
+.Fa high
+specify minimum and maximum number of unit numbers.
+There is no cost associated with the range of unit numbers, so unless the resource
+really is finite,
+.Va INT_MAX
+can be used.
+If
+.Fa mutex
+is not
+.Va NULL ,
+it is used for locking when allocating and freeing units.
+Otherwise internal mutex is used.
+.It Fn delete_unrhdr uh
+Destroy specified unit number allocator entity.
+.It Fn alloc_unr uh
+Return a new unit number.
+The lowest free number is always allocated.
+This function does not allocate memory and never sleeps, however it may
+block on mutex.
+If no free unit numbers are left
+.Va -1
+is returned.
+.It Fn alloc_unrl uh
+Same as
+.Fn alloc_unr
+except that mutex is assumed to be locked already and thus is not used.
+.It Fn free_unr uh
+Free a previously allocated unit number.
+This function may require allocating memory, and thus it can sleep.
+There is no pre-locked variant.
+.El
+.Sh CODE REFERENCES
+The above functions are implemented in
+.Pa sys/kern/subr_unit.c .
+.Sh HISTORY
+Kernel unit number allocator first appeared in
+.Fx 5.5 .
+.Sh AUTHORS
+.An -nosplit
+Kernel unit number allocator was written by
+.An Poul-Henning Kamp .
+This manpage was written by
+.An Gleb Smirnoff .