diff options
Diffstat (limited to 'static/freebsd/man9/unr.9')
| -rw-r--r-- | static/freebsd/man9/unr.9 | 191 |
1 files changed, 191 insertions, 0 deletions
diff --git a/static/freebsd/man9/unr.9 b/static/freebsd/man9/unr.9 new file mode 100644 index 00000000..73717dd9 --- /dev/null +++ b/static/freebsd/man9/unr.9 @@ -0,0 +1,191 @@ +.\" 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. +.\" +.Dd April 21, 2022 +.Dt UNR 9 +.Os +.Sh NAME +.Nm new_unrhdr , +.Nm clean_unrhdr , +.Nm clear_unrhdr , +.Nm delete_unrhdr , +.Nm alloc_unr , +.Nm alloc_unr_specific , +.Nm free_unr , +.Nm create_iter_unr , +.Nm next_iter_unr , +.Nm free_iter_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 clean_unrhdr "struct unrhdr *uh" +.Ft void +.Fn clean_unrhdrl "struct unrhdr *uh" +.Ft void +.Fn clear_unrhdr "struct unrhdr *uh" +.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 int +.Fn alloc_unr_specific "struct unrhdr *uh" "u_int item" +.Ft void +.Fn free_unr "struct unrhdr *uh" "u_int item" +.Ft void * +.Fn create_iter_unr "struct unrhdr *uh" +.Ft int +.Fn next_iter_unr "void *handle" +.Ft void +.Fn free_iter_unr "void *handle" +.Sh DESCRIPTION +The kernel unit number allocator is a generic facility, which allows to allocate +unit numbers within a specified range. +.Bl -tag -width indent +.It Fn new_unrhdr low high mutex +Initialize a new unit number allocator entity. +The +.Fa low +and +.Fa high +arguments +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, +.Dv INT_MAX +can be used. +If +.Fa mutex +is not +.Dv NULL , +it is used for locking when allocating and freeing units. +If the passed value is the token +.Va UNR_NO_MTX , +then no locking is applied internally. +Otherwise, internal mutex is used. +.It Fn clear_unrhdr uh +Clear all units from the specified unit number allocator entity. +This function resets the entity as if it were just initialized with +.Fn new_unrhdr . +.It Fn delete_unrhdr uh +Delete specified unit number allocator entity. +This function frees the memory associated with the entity, it does not free +any units. +To free all units use +.Fn clear_unrhdr . +.It Fn clean_unrhdr uh +Freeing unit numbers might result in some internal memory becoming unused. +There are +.Nm unit +allocator consumers that cannot tolerate taking +.Xr malloc 9 +locks to free the memory, while having their unit mutex locked. +For this reason, free of the unused memory after delete is postponed +until the consumer can afford calling into the +.Xr malloc 9 +subsystem. +Call +.Fn clean_unrhdr uh +to do the cleanup. +In particular, this needs to be done before freeing a unr, if +a deletion of units could have been performed. +.It Fn clean_unrhdrl +Same as +.Fn clean_unrhdr , +but assumes that the unr mutex is already owned, if any. +.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 a mutex. +If no free unit numbers are left, +.Li \-1 +is returned. +.It Fn alloc_unrl uh +Same as +.Fn alloc_unr +except that mutex is assumed to be already locked and thus is not used. +.It Fn alloc_unr_specific uh item +Allocate a specific unit number. +This function allocates memory and thus may sleep. +The allocated unit number is returned on success. +If the specified number is already allocated or out of the range, +.Li \-1 +is returned. +.It Fn free_unr uh item +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 ITERATOR INTERFACE +The +.Nm unr +facility provides an interface to iterate over all allocated units +for the given +.Dv unrhdr . +Iterators are identified by an opaque handle. +More than one iterators can operate simultaneously; the iterator position +data is recorded only in the iterator handle. +.Pp +Consumers must ensure that the unit allocator is not modified between +calls to the iterator functions. +In particular, the internal allocator mutex cannot provide consistency, +because it is acquired and dropped inside the +.Fn next_iter_unr +function. +If the allocator was modified, it is safe to free the iterator with +.Fn free_iter_unr +method nevertheless. +.Bl -tag -width indent +.It Fn create_iter_unr uh +Create an iterator. +Return the handle that should be passed to other iterator functions. +.It Fn next_iter_unr handle +Return the value of the next unit. +Units are returned in ascending order. +A return value of +.Li \-1 +indicates the end of iteration, in which +case +.Li \-1 +is returned for all future calls. +.It Fn free_iter_unr handle +Free the iterator, handle is no longer valid. +.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 6.0 . +.Sh AUTHORS +.An -nosplit +Kernel unit number allocator was written by +.An Poul-Henning Kamp . +This manpage was written by +.An Gleb Smirnoff . |