Index: head/lib/libmd/sha512.3 =================================================================== --- head/lib/libmd/sha512.3 (revision 331093) +++ head/lib/libmd/sha512.3 (revision 331094) @@ -1,210 +1,210 @@ .\" .\" ---------------------------------------------------------------------------- .\" "THE BEER-WARE LICENSE" (Revision 42): .\" wrote this file. As long as you retain this notice you .\" can do whatever you want with this stuff. If we meet some day, and you think .\" this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp .\" ---------------------------------------------------------------------------- .\" .\" From: Id: mdX.3,v 1.14 1999/02/11 20:31:49 wollman Exp .\" $FreeBSD$ .\" .Dd April 22, 2016 .Dt SHA512 3 .Os .Sh NAME .Nm SHA512_Init , .Nm SHA512_Update , .Nm SHA512_Final , .Nm SHA512_End , .Nm SHA512_File , .Nm SHA512_FileChunk , .Nm SHA512_Data , .Nm SHA384_Init , .Nm SHA384_Update , .Nm SHA384_Final , .Nm SHA384_End , .Nm SHA384_File , .Nm SHA384_FileChunk , -.Nm SHA384_Data, +.Nm SHA384_Data , .Nm SHA512_256_Init , .Nm SHA512_256_Update , .Nm SHA512_256_Final , .Nm SHA512_256_End , .Nm SHA512_256_File , .Nm SHA512_256_FileChunk , .Nm SHA512_256_Data .Nd calculate the FIPS 180-4 ``SHA-512'' family of message digests .Sh LIBRARY .Lb libmd .Sh SYNOPSIS .In sys/types.h .In sha512.h .Ft void .Fn SHA512_Init "SHA512_CTX *context" .Ft void .Fn SHA512_Update "SHA512_CTX *context" "const unsigned char *data" "size_t len" .Ft void .Fn SHA512_Final "unsigned char digest[64]" "SHA512_CTX *context" .Ft "char *" .Fn SHA512_End "SHA512_CTX *context" "char *buf" .Ft "char *" .Fn SHA512_File "const char *filename" "char *buf" .Ft "char *" .Fn SHA512_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" .Ft "char *" .Fn SHA512_Data "const unsigned char *data" "unsigned int len" "char *buf" .In sha384.h .Ft void .Fn SHA384_Init "SHA384_CTX *context" .Ft void .Fn SHA384_Update "SHA384_CTX *context" "const unsigned char *data" "size_t len" .Ft void .Fn SHA384_Final "unsigned char digest[48]" "SHA384_CTX *context" .Ft "char *" .Fn SHA384_End "SHA384_CTX *context" "char *buf" .Ft "char *" .Fn SHA384_File "const char *filename" "char *buf" .Ft "char *" .Fn SHA384_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" .Ft "char *" .Fn SHA384_Data "const unsigned char *data" "unsigned int len" "char *buf" .In sha512t.h .Ft void .Fn SHA512_256_Init "SHA512_CTX *context" .Ft void .Fn SHA512_256_Update "SHA512_CTX *context" "const unsigned char *data" "size_t len" .Ft void .Fn SHA512_256_Final "unsigned char digest[32]" "SHA512_CTX *context" .Ft "char *" .Fn SHA512_256_End "SHA512_CTX *context" "char *buf" .Ft "char *" .Fn SHA512_256_File "const char *filename" "char *buf" .Ft "char *" .Fn SHA512_256_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" .Ft "char *" .Fn SHA512_256_Data "const unsigned char *data" "unsigned int len" "char *buf" .Sh DESCRIPTION The .Li SHA512_ functions calculate a 512-bit cryptographic checksum (digest) for any number of input bytes. A cryptographic checksum is a one-way hash function; that is, it is computationally impractical to find the input corresponding to a particular output. This net result is a .Dq fingerprint of the input-data, which does not disclose the actual input. .Pp The .Fn SHA512_Init , .Fn SHA512_Update , and .Fn SHA512_Final functions are the core functions. Allocate an .Vt SHA512_CTX , initialize it with .Fn SHA512_Init , run over the data with .Fn SHA512_Update , and finally extract the result using .Fn SHA512_Final . .Pp .Fn SHA512_End is a wrapper for .Fn SHA512_Final which converts the return value to a 129-character (including the terminating '\e0') .Tn ASCII string which represents the 512 bits in hexadecimal. .Pp .Fn SHA512_File calculates the digest of a file, and uses .Fn SHA512_End to return the result. If the file cannot be opened, a null pointer is returned. .Fn SHA512_FileChunk is similar to .Fn SHA512_File , but it only calculates the digest over a byte-range of the file specified, starting at .Fa offset and spanning .Fa length bytes. If the .Fa length parameter is specified as 0, or more than the length of the remaining part of the file, .Fn SHA512_FileChunk calculates the digest from .Fa offset to the end of file. .Fn SHA512_Data calculates the digest of a chunk of data in memory, and uses .Fn SHA512_End to return the result. .Pp When using .Fn SHA512_End , .Fn SHA512_File , or .Fn SHA512_Data , the .Fa buf argument can be a null pointer, in which case the returned string is allocated with .Xr malloc 3 and subsequently must be explicitly deallocated using .Xr free 3 after use. If the .Fa buf argument is non-null it must point to at least 129 characters of buffer space. .Pp The .Li SHA384_ and .Li SHA512_256_ functions are identical to the .Li SHA512_ functions except they use a different initial hash value and the output is truncated to 384 bits and 256 bits respectively. .Pp .Fn SHA384_End is a wrapper for .Fn SHA384_Final which converts the return value to a 97-character (including the terminating '\e0') .Tn ASCII string which represents the 384 bits in hexadecimal. .Pp .Fn SHA512_256_End is a wrapper for .Fn SHA512_Final which converts the return value to a 65-character (including the terminating '\e0') .Tn ASCII string which represents the 256 bits in hexadecimal. .Sh SEE ALSO .Xr md4 3 , .Xr md5 3 , .Xr ripemd 3 , .Xr sha 3 , .Xr sha256 3 , .Xr sha512 3 , .Xr skein 3 .Sh HISTORY These functions appeared in .Fx 9.0 . .Sh AUTHORS The core hash routines were implemented by Colin Percival based on the published .Tn FIPS 180-2 standard. .Sh BUGS No method is known to exist which finds two files having the same hash value, nor to find a file with a specific hash value. There is on the other hand no guarantee that such a method does not exist. Index: head/share/man/man9/cnv.9 =================================================================== --- head/share/man/man9/cnv.9 (revision 331093) +++ head/share/man/man9/cnv.9 (revision 331094) @@ -1,214 +1,214 @@ .\" .\" Copyright (c) 2016 Adam Starak .\" 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 October 26, 2017 .Dt CNV 9 .Os .Sh NAME -.Nm cnvlist_get, -.Nm cnvlist_take, -.Nm cnvlist_free, +.Nm cnvlist_get , +.Nm cnvlist_take , +.Nm cnvlist_free .Nd "API for managing name/value pairs by cookie." .Sh LIBRARY .Lb libnv .Sh SYNOPSIS .In sys/cnv.h .Ft const char * .Fn cnvlist_name "void *cookiep" .Ft int .Fn cnvlist_type "void *cookiep" .\" .Ft bool .Fn cnvlist_get_bool "void *cookiep" .Ft uint64_t .Fn cnvlist_get_number "void *cookiep" .Ft "const char *" .Fn cnvlist_get_string "void *cookiep" .Ft "const nvlist_t *" .Fn cnvlist_get_nvlist "void *cookiep" .Ft "const void *" .Fn cnvlist_get_binary "void *cookiep" "size_t *sizep" .Ft "const bool *" .Fn cnvlist_get_bool_array "void *cookiep" "size_t *nitemsp" .Ft "const uint64_t *" .Fn cnvlist_get_number_array "void *cookiep" "size_t *nitemsp" .Ft "const char * const *" .Fn cnvlist_get_string_array "void *cookiep" "size_t *nitemsp" .Ft "const nvlist_t * const *" .Fn cnvlist_get_nvlist_array "void *cookiep" "size_t *nitemsp" .Ft int .Fn cnvlist_get_descriptor "void *cookiep" .Ft "const int *" .Fn cnvlist_get_descriptor_array "void *cookiep" "size_t *nitemsp" .\" .Ft bool .Fn cnvlist_take_bool "void *cookiep" .Ft uint64_t .Fn cnvlist_take_number "void *cookiep" .Ft "const char *" .Fn cnvlist_take_string "void *cookiep" .Ft "const nvlist_t *" .Fn cnvlist_take_nvlist "void *cookiep" .Ft "const void *" .Fn cnvlist_take_binary "void *cookiep" "size_t *sizep" .Ft "const bool *" .Fn cnvlist_take_bool_array "void *cookiep" "size_t *nitemsp" .Ft "const uint64_t *" .Fn cnvlist_take_number_array "void *cookiep" "size_t *nitemsp" .Ft "const char * const *" .Fn cnvlist_take_string_array "void *cookiep" "size_t *nitemsp" .Ft "const nvlist_t * const *" .Fn cnvlist_take_nvlist_array "void *cookiep" "size_t *nitemsp" .Ft int .Fn cnvlist_take_descriptor "void *cookiep" .Ft "const int *" .Fn cnvlist_take_descriptor_array "void *cookiep" "size_t *nitemsp" .\" .Ft void .Fn cnvlist_free_null "nvlist_t *nvl" "void *cookiep" .Ft void .Fn cnvlist_free_bool "nvlist_t *nvl" "void *cookiep" .Ft void .Fn cnvlist_free_number "nvlist_t *nvl" "void *cookiep" .Ft void .Fn cnvlist_free_string "nvlist_t *nvl" "void *cookiep" .Ft void .Fn cnvlist_free_nvlist "nvlist_t *nvl" "void *cookiep" .Ft void .Fn cnvlist_free_descriptor "nvlist_t *nvl" "void *cookiep" .Ft void .Fn cnvlist_free_binary "nvlist_t *nvl" "void *cookiep" .Ft void .Fn cnvlist_free_bool_array "nvlist_t *nvl" "void *cookiep" .Ft void .Fn cnvlist_free_number_array "nvlist_t *nvl" "void *cookiep" .Ft void .Fn cnvlist_free_string_array "nvlist_t *nvl" "void *cookiep" .Ft void .Fn cnvlist_free_nvlist_array "nvlist_t *nvl" "void *cookiep" .Ft void .Fn cnvlist_free_descriptor_array "nvlist_t *nvl" "void *cookiep" .Sh DESCRIPTION The .Nm libnv library permits easy management of name/value pairs and can send and receive them over sockets. For more information, also see .Xr nv 9 . .Pp The concept of cookies is explained in .Fn nvlist_next , .Fn nvlist_get_parent , and .Fn nvlist_get_pararr from .Xr nv 9 . .Pp The .Fn cnvlist_name function returns the name of an element associated with the given cookie. .Pp The .Fn cnvlist_type function returns the type of an element associated with the given cookie. Types which can be returned are described in .Xr nv 9 . .Pp The .Nm cnvlist_get family of functions obtains the value associated with the given cookie. Returned strings, nvlists, descriptors, binaries, or arrays must not be modified by the user, since they still belong to the nvlist. The nvlist must not be in an error state. .Pp The .Nm cnvlist_take family of functions returns the value associated with the given cookie and removes the element from the nvlist. When the value is a string, binary, or array value, the caller is responsible for freeing the returned memory with .Fn free 3 . When the value is an nvlist, the caller is responsible for destroying the returned nvlist with .Fn nvlist_destroy . When the value is a descriptor, the caller is responsible for closing the returned descriptor with the .Fn close 2 . .Pp The .Nm cnvlist_free family of functions removes an element of the supplied cookie and frees all resources. If an element of the given cookie has the wrong type or does not exist, the program is aborted. .Sh EXAMPLE The following example demonstrates how to deal with cnvlist API. .Bd -literal int type; void *cookie, *scookie, *bcookie; nvlist_t *nvl; char *name; nvl = nvlist_create(0); nvlist_add_bool(nvl, "test", 1 == 2); nvlist_add_string(nvl, "test2", "cnvlist"); cookie = NULL; while (nvlist_next(nvl, &type, &cookie) != NULL) { switch (type) { case NV_TYPE_BOOL: printf("test: %d\\n", cnvlist_get_bool(cookie)); bcookie = cookie; break; case NV_TYPE_STRING: printf("test2: %s\\n", cnvlist_get_string(cookie)); scookie = cookie; break; } } name = cnvlist_take_string(nvl, scookie); cnvlist_free_bool(nvl, bcookie); printf("test2: %s\\n", name); free(name); printf("nvlist_empty = %d\\n", nvlist_empty(nvl)); nvlist_destroy(nvl); return (0); .Ed .Sh SEE ALSO .Xr close 2 , .Xr free 3 , .Xr nv 9 .Sh AUTHORS The .Nm cnv API was created during the Google Summer Of Code 2016 by .An Adam Starak . Index: head/share/man/man9/owll.9 =================================================================== --- head/share/man/man9/owll.9 (revision 331093) +++ head/share/man/man9/owll.9 (revision 331094) @@ -1,93 +1,93 @@ .\" .\" Copyright (c) 2015 M. Warner Losh .\" 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. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" 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 September 22, 2016 .Dt OWLL 9 .Os .Sh NAME .Nm owll -.Nm OWLL_WRITE_ONE, -.Nm OWLL_WRITE_ZERO, -.Nm OWLL_READ_DATA, +.Nm OWLL_WRITE_ONE , +.Nm OWLL_WRITE_ZERO , +.Nm OWLL_READ_DATA , .Nm OWLL_REASET_AND_PRESENCE .Nd Dallas Semiconductor 1-Wire Link Layer Interface .Sh SYNOPSIS .Ft int .Fn OWLL_WRITE_ONE "device_t lldev" "struct ow_timing *timing" .Ft int .Fn OWLL_WRITE_ZERO "device_t lldev" "struct ow_timing *timing" .Ft int .Fn OWLL_READ_DATA "device_t lldev" "struct ow_timing *timing" "int *bit" .Ft int .Fn OWLL_RESET_AND_PRESENCE "device_t lldev" "struct ow_timing *timing" "int *bit" .Sh DESCRIPTION The .Nm interface provides access to the link layer of the Dallas Semiconductor 1-Wire from upper layers of the protocol. .Pp .Fn OWLL_WRITE_ONE and .Fn OWLL_WRITE_ZERO writes a one bit or a zero bit respectively on the 1-Wire bus. .Pp .Fn OWLL_READ_DATA reads one bit from the 1-Wire bus. This is often referred to as a .Dq Read Time Slot in the 1-Wire device data sheets. .Pp The .Fn OWLL_RESET_AND_PRESENCE function starts a reset sequence and detects if any device(s) are present on the bus. This is the beginning of all 1-Wire transactions. .Sh NOTES This interface is intended to be used only by the .Xr ow 4 device to talk to the low-level bus. By convention, the device that implements this interface is called .Xr owc 4 . Only devices that implement .Xr own 9 should call these interfaces. .Sh SEE ALSO .Xr ow 4 , .Xr owc 4 , .Xr own 9 .Sh LEGAL .Tn 1-Wire is a registered trademark of Maxim Integrated Products, Inc. .Sh HISTORY The .Nm driver first appeared in .Fx 11.0 . .Sh AUTHORS The .Nm device driver and this manual page were written by .An Warner Losh . Index: head/share/man/man9/rwlock.9 =================================================================== --- head/share/man/man9/rwlock.9 (revision 331093) +++ head/share/man/man9/rwlock.9 (revision 331094) @@ -1,337 +1,337 @@ .\" Copyright (c) 2006 Gleb Smirnoff .\" 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 November 11, 2017 .Dt RWLOCK 9 .Os .Sh NAME .Nm rwlock , .Nm rw_init , -.Nm rw_init_flags, +.Nm rw_init_flags , .Nm rw_destroy , .Nm rw_rlock , .Nm rw_wlock , .Nm rw_runlock , .Nm rw_wunlock , .Nm rw_unlock , .Nm rw_try_rlock , .Nm rw_try_upgrade , .Nm rw_try_wlock , .Nm rw_downgrade , .Nm rw_sleep , .Nm rw_initialized , .Nm rw_wowned , .Nm rw_assert , .Nm RW_SYSINIT , .Nm RW_SYSINIT_FLAGS .Nd kernel reader/writer lock .Sh SYNOPSIS .In sys/param.h .In sys/lock.h .In sys/rwlock.h .Ft void .Fn rw_init "struct rwlock *rw" "const char *name" .Ft void .Fn rw_init_flags "struct rwlock *rw" "const char *name" "int opts" .Ft void .Fn rw_destroy "struct rwlock *rw" .Ft void .Fn rw_rlock "struct rwlock *rw" .Ft void .Fn rw_wlock "struct rwlock *rw" .Ft int .Fn rw_try_rlock "struct rwlock *rw" .Ft int .Fn rw_try_wlock "struct rwlock *rw" .Ft void .Fn rw_runlock "struct rwlock *rw" .Ft void .Fn rw_wunlock "struct rwlock *rw" .Ft void .Fn rw_unlock "struct rwlock *rw" .Ft int .Fn rw_try_upgrade "struct rwlock *rw" .Ft void .Fn rw_downgrade "struct rwlock *rw" .Ft int .Fn rw_sleep "void *chan" "struct rwlock *rw" "int priority" "const char *wmesg" "int timo" .Ft int .Fn rw_initialized "const struct rwlock *rw" .Ft int .Fn rw_wowned "const struct rwlock *rw" .Pp .Cd "options INVARIANTS" .Cd "options INVARIANT_SUPPORT" .Ft void .Fn rw_assert "const struct rwlock *rw" "int what" .In sys/kernel.h .Fn RW_SYSINIT "name" "struct rwlock *rw" "const char *desc" .Fn RW_SYSINIT_FLAGS "name" "struct rwlock *rw" "const char *desc" "int flags" .Sh DESCRIPTION Reader/writer locks allow shared access to protected data by multiple threads, or exclusive access by a single thread. The threads with shared access are known as .Em readers since they only read the protected data. A thread with exclusive access is known as a .Em writer since it can modify protected data. .Pp Although reader/writer locks look very similar to .Xr sx 9 locks, their usage pattern is different. Reader/writer locks can be treated as mutexes (see .Xr mutex 9 ) with shared/exclusive semantics. Unlike .Xr sx 9 , an .Nm can be locked while holding a non-spin mutex, and an .Nm cannot be held while sleeping. The .Nm locks have priority propagation like mutexes, but priority can be propagated only to writers. This limitation comes from the fact that readers are anonymous. Another important property is that readers can always recurse, and exclusive locks can be made recursive selectively. .Ss Macros and Functions .Bl -tag -width indent .It Fn rw_init "struct rwlock *rw" "const char *name" Initialize structure located at .Fa rw as reader/writer lock, described by name .Fa name . The description is used solely for debugging purposes. This function must be called before any other operations on the lock. .It Fn rw_init_flags "struct rwlock *rw" "const char *name" "int opts" Initialize the rw lock just like the .Fn rw_init function, but specifying a set of optional flags to alter the behaviour of .Fa rw , through the .Fa opts argument. It contains one or more of the following flags: .Bl -tag -width ".Dv RW_NOPROFILE" .It Dv RW_DUPOK Witness should not log messages about duplicate locks being acquired. .It Dv RW_NOPROFILE Do not profile this lock. .It Dv RW_NOWITNESS Instruct .Xr witness 4 to ignore this lock. .It Dv RW_QUIET Do not log any operations for this lock via .Xr ktr 4 . .It Dv RW_RECURSE Allow threads to recursively acquire exclusive locks for .Fa rw . .It Dv RW_NEW If the kernel has been compiled with .Cd "option INVARIANTS" , .Fn rw_init_flags will assert that the .Fa rw has not been initialized multiple times without intervening calls to .Fn rw_destroy unless this option is specified. .El .It Fn rw_rlock "struct rwlock *rw" Lock .Fa rw as a reader. If any thread holds this lock exclusively, the current thread blocks, and its priority is propagated to the exclusive holder. The .Fn rw_rlock function can be called when the thread has already acquired reader access on .Fa rw . This is called .Dq "recursing on a lock" . .It Fn rw_wlock "struct rwlock *rw" Lock .Fa rw as a writer. If there are any shared owners of the lock, the current thread blocks. The .Fn rw_wlock function can be called recursively only if .Fa rw has been initialized with the .Dv RW_RECURSE option enabled. .It Fn rw_try_rlock "struct rwlock *rw" Try to lock .Fa rw as a reader. This function will return true if the operation succeeds, otherwise 0 will be returned. .It Fn rw_try_wlock "struct rwlock *rw" Try to lock .Fa rw as a writer. This function will return true if the operation succeeds, otherwise 0 will be returned. .It Fn rw_runlock "struct rwlock *rw" This function releases a shared lock previously acquired by .Fn rw_rlock . .It Fn rw_wunlock "struct rwlock *rw" This function releases an exclusive lock previously acquired by .Fn rw_wlock . .It Fn rw_unlock "struct rwlock *rw" This function releases a shared lock previously acquired by .Fn rw_rlock or an exclusive lock previously acquired by .Fn rw_wlock . .It Fn rw_try_upgrade "struct rwlock *rw" Attempt to upgrade a single shared lock to an exclusive lock. The current thread must hold a shared lock of .Fa rw . This will only succeed if the current thread holds the only shared lock on .Fa rw , and it only holds a single shared lock. If the attempt succeeds .Fn rw_try_upgrade will return a non-zero value, and the current thread will hold an exclusive lock. If the attempt fails .Fn rw_try_upgrade will return zero, and the current thread will still hold a shared lock. .It Fn rw_downgrade "struct rwlock *rw" Convert an exclusive lock into a single shared lock. The current thread must hold an exclusive lock of .Fa rw . .It Fn rw_sleep "void *chan" "struct rwlock *rw" "int priority" "const char *wmesg" "int timo" Atomically release .Fa rw while waiting for an event. For more details on the parameters to this function, see .Xr sleep 9 . .It Fn rw_initialized "const struct rwlock *rw" This function returns non-zero if .Fa rw has been initialized, and zero otherwise. .It Fn rw_destroy "struct rwlock *rw" This functions destroys a lock previously initialized with .Fn rw_init . The .Fa rw lock must be unlocked. .It Fn rw_wowned "const struct rwlock *rw" This function returns a non-zero value if the current thread owns an exclusive lock on .Fa rw . .It Fn rw_assert "const struct rwlock *rw" "int what" This function allows assertions specified in .Fa what to be made about .Fa rw . If the assertions are not true and the kernel is compiled with .Cd "options INVARIANTS" and .Cd "options INVARIANT_SUPPORT" , the kernel will panic. Currently the following base assertions are supported: .Bl -tag -width ".Dv RA_UNLOCKED" .It Dv RA_LOCKED Assert that current thread holds either a shared or exclusive lock of .Fa rw . .It Dv RA_RLOCKED Assert that current thread holds a shared lock of .Fa rw . .It Dv RA_WLOCKED Assert that current thread holds an exclusive lock of .Fa rw . .It Dv RA_UNLOCKED Assert that current thread holds neither a shared nor exclusive lock of .Fa rw . .El .Pp In addition, one of the following optional flags may be specified with .Dv RA_LOCKED , .Dv RA_RLOCKED , or .Dv RA_WLOCKED : .Bl -tag -width ".Dv RA_NOTRECURSED" .It Dv RA_RECURSED Assert that the current thread holds a recursive lock of .Fa rw . .It Dv RA_NOTRECURSED Assert that the current thread does not hold a recursive lock of .Fa rw . .El .El .Sh SEE ALSO .Xr locking 9 , .Xr mutex 9 , .Xr panic 9 , .Xr sema 9 , .Xr sx 9 .Sh HISTORY These functions appeared in .Fx 7.0 . .Sh AUTHORS .An -nosplit The .Nm facility was written by .An "John Baldwin" . This manual page was written by .An "Gleb Smirnoff" . .Sh BUGS A kernel without .Dv WITNESS cannot assert whether the current thread does or does not hold a read lock. .Dv RA_LOCKED and .Dv RA_RLOCKED can only assert that .Em any thread holds a read lock. They cannot ensure that the current thread holds a read lock. Further, .Dv RA_UNLOCKED can only assert that the current thread does not hold a write lock. .Pp Reader/writer is a bit of an awkward name. An .Nm can also be called a .Dq Robert Watson lock if desired. Index: head/share/man/man9/zone.9 =================================================================== --- head/share/man/man9/zone.9 (revision 331093) +++ head/share/man/man9/zone.9 (revision 331094) @@ -1,374 +1,374 @@ .\"- .\" Copyright (c) 2001 Dag-Erling Coïdan Smørgrav .\" 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 April 26, 2017 .Dt ZONE 9 .Os .Sh NAME .Nm uma_zcreate , .Nm uma_zalloc , .Nm uma_zalloc_arg , .Nm uma_zfree , .Nm uma_zfree_arg , .Nm uma_zdestroy , -.Nm uma_zone_set_max, -.Nm uma_zone_get_max, -.Nm uma_zone_get_cur, -.Nm uma_zone_set_warning, +.Nm uma_zone_set_max , +.Nm uma_zone_get_max , +.Nm uma_zone_get_cur , +.Nm uma_zone_set_warning , .Nm uma_zone_set_maxaction .Nd zone allocator .Sh SYNOPSIS .In sys/param.h .In sys/queue.h .In vm/uma.h .Ft uma_zone_t .Fo uma_zcreate .Fa "char *name" "int size" .Fa "uma_ctor ctor" "uma_dtor dtor" "uma_init uminit" "uma_fini fini" .Fa "int align" "uint16_t flags" .Fc .Ft "void *" .Fn uma_zalloc "uma_zone_t zone" "int flags" .Ft "void *" .Fn uma_zalloc_arg "uma_zone_t zone" "void *arg" "int flags" .Ft void .Fn uma_zfree "uma_zone_t zone" "void *item" .Ft void .Fn uma_zfree_arg "uma_zone_t zone" "void *item" "void *arg" .Ft void .Fn uma_zdestroy "uma_zone_t zone" .Ft int .Fn uma_zone_set_max "uma_zone_t zone" "int nitems" .Ft int .Fn uma_zone_get_max "uma_zone_t zone" .Ft int .Fn uma_zone_get_cur "uma_zone_t zone" .Ft void .Fn uma_zone_set_warning "uma_zone_t zone" "const char *warning" .Ft void .Fn uma_zone_set_maxaction "uma_zone_t zone" "void (*maxaction)(uma_zone_t)" .In sys/sysctl.h .Fn SYSCTL_UMA_MAX parent nbr name access zone descr .Fn SYSCTL_ADD_UMA_MAX ctx parent nbr name access zone descr .Fn SYSCTL_UMA_CUR parent nbr name access zone descr .Fn SYSCTL_ADD_UMA_CUR ctx parent nbr name access zone descr .Sh DESCRIPTION The zone allocator provides an efficient interface for managing dynamically-sized collections of items of similar size. The zone allocator can work with preallocated zones as well as with runtime-allocated ones, and is therefore available much earlier in the boot process than other memory management routines. .Pp A zone is an extensible collection of items of identical size. The zone allocator keeps track of which items are in use and which are not, and provides functions for allocating items from the zone and for releasing them back (which makes them available for later use). .Pp After the first allocation of an item, it will have been cleared to zeroes, however subsequent allocations will retain the contents as of the last free. .Pp The .Fn uma_zcreate function creates a new zone from which items may then be allocated from. The .Fa name argument is a text name of the zone for debugging and stats; this memory should not be freed until the zone has been deallocated. .Pp The .Fa ctor and .Fa dtor arguments are callback functions that are called by the uma subsystem at the time of the call to .Fn uma_zalloc and .Fn uma_zfree respectively. Their purpose is to provide hooks for initializing or destroying things that need to be done at the time of the allocation or release of a resource. A good usage for the .Fa ctor and .Fa dtor callbacks might be to adjust a global count of the number of objects allocated. .Pp The .Fa uminit and .Fa fini arguments are used to optimize the allocation of objects from the zone. They are called by the uma subsystem whenever it needs to allocate or free several items to satisfy requests or memory pressure. A good use for the .Fa uminit and .Fa fini callbacks might be to initialize and destroy mutexes contained within the object. This would allow one to re-use already initialized mutexes when an object is returned from the uma subsystem's object cache. They are not called on each call to .Fn uma_zalloc and .Fn uma_zfree but rather in a batch mode on several objects. .Pp The .Fa flags argument of the .Fn uma_zcreate is a subset of the following flags: .Bl -tag -width "foo" .It Dv UMA_ZONE_NOFREE Slabs of the zone are never returned back to VM. .It Dv UMA_ZONE_NODUMP Pages belonging to the zone will not be included into mini-dumps. .It Dv UMA_ZONE_PCPU An allocation from zone would have .Va mp_ncpu shadow copies, that are privately assigned to CPUs. A CPU can address its private copy using base allocation address plus multiple of current CPU id and .Fn sizeof "struct pcpu" : .Bd -literal -offset indent foo_zone = uma_zcreate(..., UMA_ZONE_PCPU); ... foo_base = uma_zalloc(foo_zone, ...); ... critical_enter(); foo_pcpu = (foo_t *)zpcpu_get(foo_base); /* do something with foo_pcpu */ critical_exit(); .Ed .It Dv UMA_ZONE_OFFPAGE By default book-keeping of items within a slab is done in the slab page itself. This flag explicitly tells subsystem that book-keeping structure should be allocated separately from special internal zone. This flag requires either .Dv UMA_ZONE_VTOSLAB or .Dv UMA_ZONE_HASH , since subsystem requires a mechanism to find a book-keeping structure to an item being freed. The subsystem may choose to prefer offpage book-keeping for certain zones implicitly. .It Dv UMA_ZONE_ZINIT The zone will have its .Ft uma_init method set to internal method that initializes a new allocated slab to all zeros. Do not mistake .Ft uma_init method with .Ft uma_ctor . A zone with .Dv UMA_ZONE_ZINIT flag would not return zeroed memory on every .Fn uma_zalloc . .It Dv UMA_ZONE_HASH The zone should use an internal hash table to find slab book-keeping structure where an allocation being freed belongs to. .It Dv UMA_ZONE_VTOSLAB The zone should use special field of .Vt vm_page_t to find slab book-keeping structure where an allocation being freed belongs to. .It Dv UMA_ZONE_MALLOC The zone is for the .Xr malloc 9 subsystem. .It Dv UMA_ZONE_VM The zone is for the VM subsystem. .El .Pp To allocate an item from a zone, simply call .Fn uma_zalloc with a pointer to that zone and set the .Fa flags argument to selected flags as documented in .Xr malloc 9 . It will return a pointer to an item if successful, or .Dv NULL in the rare case where all items in the zone are in use and the allocator is unable to grow the zone and .Dv M_NOWAIT is specified. .Pp Items are released back to the zone from which they were allocated by calling .Fn uma_zfree with a pointer to the zone and a pointer to the item. If .Fa item is .Dv NULL , then .Fn uma_zfree does nothing. .Pp The variations .Fn uma_zalloc_arg and .Fn uma_zfree_arg allow to specify an argument for the .Dv ctor and .Dv dtor functions, respectively. .Pp Created zones, which are empty, can be destroyed using .Fn uma_zdestroy , freeing all memory that was allocated for the zone. All items allocated from the zone with .Fn uma_zalloc must have been freed with .Fn uma_zfree before. .Pp The .Fn uma_zone_set_max function limits the number of items .Pq and therefore memory that can be allocated to .Fa zone . The .Fa nitems argument specifies the requested upper limit number of items. The effective limit is returned to the caller, as it may end up being higher than requested due to the implementation rounding up to ensure all memory pages allocated to the zone are utilised to capacity. The limit applies to the total number of items in the zone, which includes allocated items, free items and free items in the per-cpu caches. On systems with more than one CPU it may not be possible to allocate the specified number of items even when there is no shortage of memory, because all of the remaining free items may be in the caches of the other CPUs when the limit is hit. .Pp The .Fn uma_zone_get_max function returns the effective upper limit number of items for a zone. .Pp The .Fn uma_zone_get_cur function returns the approximate current occupancy of the zone. The returned value is approximate because appropriate synchronisation to determine an exact value is not performed by the implementation. This ensures low overhead at the expense of potentially stale data being used in the calculation. .Pp The .Fn uma_zone_set_warning function sets a warning that will be printed on the system console when the given zone becomes full and fails to allocate an item. The warning will be printed no more often than every five minutes. Warnings can be turned off globally by setting the .Va vm.zone_warnings sysctl tunable to .Va 0 . .Pp The .Fn uma_zone_set_maxaction function sets a function that will be called when the given zone becomes full and fails to allocate an item. The function will be called with the zone locked. Also, the function that called the allocation function may have held additional locks. Therefore, this function should do very little work (similar to a signal handler). .Pp The .Fn SYSCTL_UMA_MAX parent nbr name access zone descr macro declares a static .Xr sysctl oid that exports the effective upper limit number of items for a zone. The .Fa zone argument should be a pointer to .Vt uma_zone_t . A read of the oid returns value obtained through .Fn uma_zone_get_max . A write to the oid sets new value via .Fn uma_zone_set_max . The .Fn SYSCTL_ADD_UMA_MAX ctx parent nbr name access zone descr macro is provided to create this type of oid dynamically. .Pp The .Fn SYSCTL_UMA_CUR parent nbr name access zone descr macro declares a static read-only .Xr sysctl oid that exports the approximate current occupancy of the zone. The .Fa zone argument should be a pointer to .Vt uma_zone_t . A read of the oid returns value obtained through .Fn uma_zone_get_cur . The .Fn SYSCTL_ADD_UMA_CUR ctx parent nbr name zone descr macro is provided to create this type of oid dynamically. .Sh RETURN VALUES The .Fn uma_zalloc function returns a pointer to an item, or .Dv NULL if the zone ran out of unused items and .Dv M_NOWAIT was specified. .Sh SEE ALSO .Xr malloc 9 .Sh HISTORY The zone allocator first appeared in .Fx 3.0 . It was radically changed in .Fx 5.0 to function as a slab allocator. .Sh AUTHORS .An -nosplit The zone allocator was written by .An John S. Dyson . The zone allocator was rewritten in large parts by .An Jeff Roberson Aq Mt jeff@FreeBSD.org to function as a slab allocator. .Pp This manual page was written by .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . Changes for UMA by .An Jeroen Ruigrok van der Werven Aq Mt asmodai@FreeBSD.org .