diff options
Diffstat (limited to 'share/man/man3')
105 files changed, 1223 insertions, 481 deletions
diff --git a/share/man/man3/ATOMIC_VAR_INIT.3 b/share/man/man3/ATOMIC_VAR_INIT.3 index e2786027a423..b3dd242342f7 100644 --- a/share/man/man3/ATOMIC_VAR_INIT.3 +++ b/share/man/man3/ATOMIC_VAR_INIT.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd December 27, 2011 .Dt ATOMIC_VAR_INIT 3 .Os diff --git a/share/man/man3/CMSG_DATA.3 b/share/man/man3/CMSG_DATA.3 index 92c5b9736da3..27e15613217e 100644 --- a/share/man/man3/CMSG_DATA.3 +++ b/share/man/man3/CMSG_DATA.3 @@ -1,7 +1,5 @@ .\" Written by Jared Yanovich <jaredy@openbsd.org> .\" Public domain, July 3, 2005 -.\" -.\" $FreeBSD$ .Dd March 13, 2020 .Dt CMSG_DATA 3 .Os @@ -165,7 +163,7 @@ main() close(hellofd[1]); if (read(hellofd[0], buf, HELLOLEN) == -1) - err(EX_IOERR, "faild to receive 'hello'"); + err(EX_IOERR, "failed to receive 'hello'"); printf("parent: received '%s'\\n", buf); break; } diff --git a/share/man/man3/Makefile b/share/man/man3/Makefile index fa4f751ce553..18e439491793 100644 --- a/share/man/man3/Makefile +++ b/share/man/man3/Makefile @@ -1,9 +1,10 @@ -# @(#)Makefile 8.2 (Berkeley) 12/13/93 -# $FreeBSD$ - .include <src.opts.mk> -MAN= arb.3 \ +PACKAGE= clibs +MANSUBPACKAGE= -dev + +MAN= alloca.3 \ + arb.3 \ assert.3 \ ATOMIC_VAR_INIT.3 \ bitstring.3 \ @@ -27,8 +28,10 @@ MAN= arb.3 \ queue.3 \ sigevent.3 \ siginfo.3 \ + snl.3 \ stats.3 \ stdarg.3 \ + stdckdint.3 \ sysexits.3 \ tgmath.3 \ timeradd.3 \ @@ -215,6 +218,8 @@ MLINKS+= queue.3 LIST_CLASS_ENTRY.3 \ queue.3 LIST_NEXT.3 \ queue.3 LIST_PREV.3 \ queue.3 LIST_REMOVE.3 \ + queue.3 LIST_REPLACE.3 \ + queue.3 LIST_SPLIT_AFTER.3 \ queue.3 LIST_SWAP.3 \ queue.3 SLIST_CLASS_ENTRY.3 \ queue.3 SLIST_CLASS_HEAD.3 \ @@ -235,6 +240,7 @@ MLINKS+= queue.3 LIST_CLASS_ENTRY.3 \ queue.3 SLIST_REMOVE_AFTER.3 \ queue.3 SLIST_REMOVE_HEAD.3 \ queue.3 SLIST_REMOVE_PREVPTR.3 \ + queue.3 SLIST_SPLIT_AFTER.3 \ queue.3 SLIST_SWAP.3 \ queue.3 STAILQ_CLASS_ENTRY.3 \ queue.3 STAILQ_CLASS_HEAD.3 \ @@ -257,6 +263,8 @@ MLINKS+= queue.3 LIST_CLASS_ENTRY.3 \ queue.3 STAILQ_REMOVE.3 \ queue.3 STAILQ_REMOVE_AFTER.3 \ queue.3 STAILQ_REMOVE_HEAD.3 \ + queue.3 STAILQ_REVERSE.3 \ + queue.3 STAILQ_SPLIT_AFTER.3 \ queue.3 STAILQ_SWAP.3 \ queue.3 TAILQ_CLASS_ENTRY.3 \ queue.3 TAILQ_CLASS_HEAD.3 \ @@ -283,6 +291,8 @@ MLINKS+= queue.3 LIST_CLASS_ENTRY.3 \ queue.3 TAILQ_NEXT.3 \ queue.3 TAILQ_PREV.3 \ queue.3 TAILQ_REMOVE.3 \ + queue.3 TAILQ_REPLACE.3 \ + queue.3 TAILQ_SPLIT_AFTER.3 \ queue.3 TAILQ_SWAP.3 MLINKS+= stats.3 stats_tpl_alloc.3 \ stats.3 stats_tpl_fetch_allocid.3 \ @@ -310,6 +320,9 @@ MLINKS+= stdarg.3 va_arg.3 \ stdarg.3 va_end.3 \ stdarg.3 varargs.3 \ stdarg.3 va_start.3 +MLINKS+= stdckdint.3 ckd_add.3 \ + stdckdint.3 ckd_sub.3 \ + stdckdint.3 ckd_mul.3 MLINKS+= timeradd.3 timerclear.3 \ timeradd.3 timercmp.3 \ timeradd.3 timerisset.3 \ @@ -320,6 +333,7 @@ MLINKS+= timeradd.3 timerclear.3 \ timeradd.3 timespecisset.3 \ timeradd.3 timespeccmp.3 MLINKS+= tree.3 RB_AUGMENT.3 \ + tree.3 RB_AUGMENT_CHECK.3 \ tree.3 RB_EMPTY.3 \ tree.3 RB_ENTRY.3 \ tree.3 RB_FIND.3 \ @@ -446,11 +460,12 @@ PTHREAD_MAN= pthread.3 \ pthread_set_name_np.3 \ pthread_setspecific.3 \ pthread_sigmask.3 \ + pthread_sigqueue.3 \ + pthread_signals_block_np.3 \ pthread_spin_init.3 \ pthread_spin_lock.3 \ pthread_suspend_all_np.3 \ pthread_suspend_np.3 \ - pthread_switch_add_np.3 \ pthread_testcancel.3 \ pthread_yield.3 @@ -512,10 +527,11 @@ PTHREAD_MLINKS+=pthread_schedparam.3 pthread_getschedparam.3 \ PTHREAD_MLINKS+=pthread_set_name_np.3 pthread_get_name_np.3 \ pthread_set_name_np.3 pthread_getname_np.3 \ pthread_set_name_np.3 pthread_setname_np.3 +PTHREAD_MLINKS+=pthread_signals_block_np.3 \ + pthread_signals_unblock_np.3 PTHREAD_MLINKS+=pthread_spin_init.3 pthread_spin_destroy.3 \ pthread_spin_lock.3 pthread_spin_trylock.3 \ pthread_spin_lock.3 pthread_spin_unlock.3 -PTHREAD_MLINKS+=pthread_switch_add_np.3 pthread_switch_delete_np.3 PTHREAD_MLINKS+=pthread_testcancel.3 pthread_setcancelstate.3 \ pthread_testcancel.3 pthread_setcanceltype.3 PTHREAD_MLINKS+=pthread_join.3 pthread_peekjoin_np.3 \ diff --git a/share/man/man3/Makefile.depend b/share/man/man3/Makefile.depend index f80275d86ab1..11aba52f82cf 100644 --- a/share/man/man3/Makefile.depend +++ b/share/man/man3/Makefile.depend @@ -1,4 +1,3 @@ -# $FreeBSD$ # Autogenerated - do NOT edit! DIRDEPS = \ diff --git a/share/man/man3/Q_FRAWMASK.3 b/share/man/man3/Q_FRAWMASK.3 index d4def82300be..4d03b2596c80 100644 --- a/share/man/man3/Q_FRAWMASK.3 +++ b/share/man/man3/Q_FRAWMASK.3 @@ -23,8 +23,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd July 8, 2018 .Dt Q_FRAWMASK 3 .Os diff --git a/share/man/man3/Q_IFRAWMASK.3 b/share/man/man3/Q_IFRAWMASK.3 index 522b2b480ea3..b6885084ff43 100644 --- a/share/man/man3/Q_IFRAWMASK.3 +++ b/share/man/man3/Q_IFRAWMASK.3 @@ -23,8 +23,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd July 8, 2018 .Dt Q_IFRAWMASK 3 .Os diff --git a/share/man/man3/Q_INI.3 b/share/man/man3/Q_INI.3 index 867d5e20031c..b7794d729f48 100644 --- a/share/man/man3/Q_INI.3 +++ b/share/man/man3/Q_INI.3 @@ -23,8 +23,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd July 8, 2018 .Dt Q_INI 3 .Os diff --git a/share/man/man3/Q_IRAWMASK.3 b/share/man/man3/Q_IRAWMASK.3 index 16a47e06a733..a15b885c946e 100644 --- a/share/man/man3/Q_IRAWMASK.3 +++ b/share/man/man3/Q_IRAWMASK.3 @@ -23,8 +23,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd July 8, 2018 .Dt Q_IRAWMASK 3 .Os diff --git a/share/man/man3/Q_QABS.3 b/share/man/man3/Q_QABS.3 index 8d5c2883d4a5..31219e1f9218 100644 --- a/share/man/man3/Q_QABS.3 +++ b/share/man/man3/Q_QABS.3 @@ -23,8 +23,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd July 8, 2018 .Dt Q_QABS 3 .Os diff --git a/share/man/man3/Q_QADDI.3 b/share/man/man3/Q_QADDI.3 index 2e03b2e7a424..5b1bc8c26023 100644 --- a/share/man/man3/Q_QADDI.3 +++ b/share/man/man3/Q_QADDI.3 @@ -23,8 +23,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd July 8, 2018 .Dt Q_QADDI 3 .Os diff --git a/share/man/man3/Q_QADDQ.3 b/share/man/man3/Q_QADDQ.3 index 26db644f34e3..d6a7df7f5e98 100644 --- a/share/man/man3/Q_QADDQ.3 +++ b/share/man/man3/Q_QADDQ.3 @@ -23,8 +23,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd July 8, 2018 .Dt Q_QADDQ 3 .Os diff --git a/share/man/man3/Q_SIGNED.3 b/share/man/man3/Q_SIGNED.3 index e8f79c55cbc3..528757dccbd5 100644 --- a/share/man/man3/Q_SIGNED.3 +++ b/share/man/man3/Q_SIGNED.3 @@ -23,8 +23,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd July 8, 2018 .Dt Q_SIGNED 3 .Os diff --git a/share/man/man3/Q_SIGNSHFT.3 b/share/man/man3/Q_SIGNSHFT.3 index a12a182fe7d1..ce355560a656 100644 --- a/share/man/man3/Q_SIGNSHFT.3 +++ b/share/man/man3/Q_SIGNSHFT.3 @@ -23,8 +23,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd July 8, 2018 .Dt Q_SIGNSHFT 3 .Os diff --git a/share/man/man3/alloca.3 b/share/man/man3/alloca.3 new file mode 100644 index 000000000000..fd88014dbb33 --- /dev/null +++ b/share/man/man3/alloca.3 @@ -0,0 +1,83 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. 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. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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 29, 2025 +.Dt ALLOCA 3 +.Os +.Sh NAME +.Nm alloca +.Nd memory allocator +.Sh SYNOPSIS +.In stdlib.h +.Ft void * +.Fn alloca "size_t size" +.Sh DESCRIPTION +The +.Fn alloca +function +allocates +.Fa size +bytes of space in the stack frame of the caller. +This temporary space is automatically freed on +return. +.Sh RETURN VALUES +The +.Fn alloca +function returns a pointer to the beginning of the allocated space. +.Sh SEE ALSO +.Xr brk 2 , +.Xr calloc 3 , +.Xr getpagesize 3 , +.Xr malloc 3 , +.Xr realloc 3 +.Sh HISTORY +The +.Fn alloca +function appeared in +.At 32v . +.\" .Bx ?? . +.\" The function appeared in 32v, pwb and pwb.2 and in 3bsd 4bsd +.\" The first man page (or link to a man page that I can find at the +.\" moment is 4.3... +.Sh BUGS +The +.Fn alloca +function +is machine and compiler dependent; +its use is discouraged. +.Pp +The +.Fn alloca +function is slightly unsafe because it cannot ensure that the pointer +returned points to a valid and usable block of memory. +The allocation made may exceed the bounds of the stack, or even go +further into other objects in memory, and +.Fn alloca +cannot determine such an error. +Avoid +.Fn alloca +with large unbounded allocations. diff --git a/share/man/man3/arb.3 b/share/man/man3/arb.3 index 14ea77c2b35a..e33ef3a37f7d 100644 --- a/share/man/man3/arb.3 +++ b/share/man/man3/arb.3 @@ -29,8 +29,6 @@ .\" (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 14, 2019 .Dt ARB 3 .Os @@ -266,7 +264,7 @@ variant includes a suffix denoting the signed integer data type size used to store array indices. For example, .Fn ARB_HEAD8 -creates a red-black tree head strucutre with 8-bit signed array indices capable +creates a red-black tree head structure with 8-bit signed array indices capable of indexing up to 128 entries. .Pp The diff --git a/share/man/man3/assert.3 b/share/man/man3/assert.3 index cc23f96360f0..f219aa1d6743 100644 --- a/share/man/man3/assert.3 +++ b/share/man/man3/assert.3 @@ -25,9 +25,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" @(#)assert.3 8.1 (Berkeley) 6/9/93 -.\" $FreeBSD$ -.\" .Dd April 20, 2021 .Dt ASSERT 3 .Os @@ -123,19 +120,15 @@ If none is provided, it only points at the constraint. .Xr abort2 2 , .Xr abort 3 .Sh STANDARDS -.Rs The .Fn assert macro conforms to .St -isoC-99 . -.Re .Pp -.Rs The .Fn static_assert macro conforms to .St -isoC-2011 . -.Re .Sh HISTORY An .Nm diff --git a/share/man/man3/bitstring.3 b/share/man/man3/bitstring.3 index c6f0dfe45c12..07558bd41ec3 100644 --- a/share/man/man3/bitstring.3 +++ b/share/man/man3/bitstring.3 @@ -55,10 +55,7 @@ .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGES. .\" -.\" @(#)bitstring.3 8.1 (Berkeley) 7/19/93 -.\" $FreeBSD$ -.\" -.Dd August 8, 2021 +.Dd November 21, 2023 .Dt BITSTRING 3 .Os .Sh NAME @@ -86,49 +83,49 @@ .Sh SYNOPSIS .In bitstring.h .Ft bitstr_t * -.Fn bit_alloc "int nbits" +.Fn bit_alloc "size_t nbits" .Ft void -.Fn bit_decl "bitstr_t *name" "int nbits" +.Fn bit_decl "bitstr_t *name" "size_t nbits" .Ft void -.Fn bit_clear "bitstr_t *name" "int bit" +.Fn bit_clear "bitstr_t *name" "size_t bit" .Ft void -.Fn bit_count "bitstr_t *name" "int count" "int nbits" "int *value" +.Fn bit_count "bitstr_t *name" "size_t count" "size_t nbits" "ssize_t *value" .Ft void -.Fn bit_ffc "bitstr_t *name" "int nbits" "int *value" +.Fn bit_ffc "bitstr_t *name" "size_t nbits" "ssize_t *value" .Ft void -.Fn bit_ffs "bitstr_t *name" "int nbits" "int *value" +.Fn bit_ffs "bitstr_t *name" "size_t nbits" "ssize_t *value" .Ft void -.Fn bit_ffc_at "bitstr_t *name" "int start" "int nbits" "int *value" +.Fn bit_ffc_at "bitstr_t *name" "size_t start" "size_t nbits" "ssize_t *value" .Ft void -.Fn bit_ffs_at "bitstr_t *name" "int start" "int nbits" "int *value" +.Fn bit_ffs_at "bitstr_t *name" "size_t start" "size_t nbits" "ssize_t *value" .Ft void -.Fn bit_ff_at "bitstr_t *name" "int start" "int nbits" "int match" "int *value" +.Fn bit_ff_at "bitstr_t *name" "size_t start" "size_t nbits" "int match" "ssize_t *value" .Ft void -.Fn bit_ffc_area "bitstr_t *name" "int nbits" "int size" "int *value" +.Fn bit_ffc_area "bitstr_t *name" "size_t nbits" "size_t size" "ssize_t *value" .Ft void -.Fn bit_ffs_area "bitstr_t *name" "int nbits" "int size" "int *value" +.Fn bit_ffs_area "bitstr_t *name" "size_t nbits" "size_t size" "ssize_t *value" .Ft void -.Fn bit_ffc_area_at "bitstr_t *name" "int start" "int nbits" "int size" "int *value" +.Fn bit_ffc_area_at "bitstr_t *name" "size_t start" "size_t nbits" "size_t size" "ssize_t *value" .Ft void -.Fn bit_ffs_area_at "bitstr_t *name" "int start" "int nbits" "int size" "int *value" +.Fn bit_ffs_area_at "bitstr_t *name" "size_t start" "size_t nbits" "size_t size" "ssize_t *value" .Ft void -.Fn bit_ff_area_at "bitstr_t *name" "int start" "int nbits" "int size" "int match" "int *value" -.Fn bit_foreach "bitstr_t *name" "int nbits" "int var" -.Fn bit_foreach_at "bitstr_t *name" "int start" "int nbits" "int var" -.Fn bit_foreach_unset "bitstr_t *name" "int nbits" "int var" -.Fn bit_foreach_unset_at "bitstr_t *name" "int start" "int nbits" "int var" +.Fn bit_ff_area_at "bitstr_t *name" "size_t start" "size_t nbits" "size_t size" "int match" "ssize_t *value" +.Fn bit_foreach "bitstr_t *name" "size_t nbits" "size_t var" +.Fn bit_foreach_at "bitstr_t *name" "size_t start" "size_t nbits" "size_t var" +.Fn bit_foreach_unset "bitstr_t *name" "size_t nbits" "size_t var" +.Fn bit_foreach_unset_at "bitstr_t *name" "size_t start" "size_t nbits" "size_t var" .Ft void -.Fn bit_nclear "bitstr_t *name" "int start" "int stop" +.Fn bit_nclear "bitstr_t *name" "size_t start" "size_t stop" .Ft void -.Fn bit_nset "bitstr_t *name" "int start" "int stop" +.Fn bit_nset "bitstr_t *name" "size_t start" "size_t stop" .Ft int -.Fn bit_ntest "bitstr_t *name" "int start" "int stop" "int match" +.Fn bit_ntest "bitstr_t *name" "size_t start" "size_t stop" "int match" .Ft void -.Fn bit_set "bitstr_t *name" "int bit" +.Fn bit_set "bitstr_t *name" "size_t bit" .Ft int -.Fn bitstr_size "int nbits" +.Fn bitstr_size "size_t nbits" .Ft int -.Fn bit_test "bitstr_t *name" "int bit" +.Fn bit_test "bitstr_t *name" "size_t bit" .Sh DESCRIPTION These macros operate on strings of bits. .Pp @@ -372,7 +369,7 @@ bits in the array of bits referenced by .Fa name , at or after the zero-based bit index -.Fa start +.Fa start in which all bits have the value .Fa match . If no sequence of contiguous such bits of the specified diff --git a/share/man/man3/end.3 b/share/man/man3/end.3 index 66ad47b5a528..538003424724 100644 --- a/share/man/man3/end.3 +++ b/share/man/man3/end.3 @@ -25,9 +25,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" @(#)end.3 6.4 (Berkeley) 1/24/94 -.\" $FreeBSD$ -.\" .Dd August 28, 2000 .Dt END 3 .Os diff --git a/share/man/man3/fpgetround.3 b/share/man/man3/fpgetround.3 index c6f013072143..c827122e462f 100644 --- a/share/man/man3/fpgetround.3 +++ b/share/man/man3/fpgetround.3 @@ -25,9 +25,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" @(#)fpgetround.3 1.0 (Berkeley) 9/23/93 -.\" $FreeBSD$ -.\" .Dd December 3, 2010 .Dt FPGETROUND 3 .Os diff --git a/share/man/man3/intro.3 b/share/man/man3/intro.3 index d6dff3ab3782..0cecdcab4069 100644 --- a/share/man/man3/intro.3 +++ b/share/man/man3/intro.3 @@ -24,11 +24,7 @@ .\" 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. -.\" -.\" @(#)intro.3 8.1 (Berkeley) 6/5/93 -.\" $FreeBSD$ -.\" -.Dd December 18, 2021 +.Dd November 27, 2024 .Dt INTRO 3 .Os .Sh NAME @@ -231,6 +227,13 @@ See The POSIX threads library. See .Xr pthread 3 . +.It Em libstdthreads +.Pq Fl l Ns Ar stdthreads +The ISO C11 standard +.In threads.h +library. +See +.Xr thrd_create 3 . .It Em libsysdecode .Pq Fl l Ns Ar sysdecode The system argument decoding library. @@ -265,20 +268,108 @@ See .Bl -tag -width /usr/lib/libm_p.a -compact .It Pa /usr/lib/libc.a the C library -.It Pa /usr/lib/libc_p.a -the C library compiled for profiling .It Pa /usr/lib/libm.a the math library -.It Pa /usr/lib/libm_p.a -the math library compiled for profiling .El +.Sh LIBRARY TYPES +The system libraries are located in +.Pa /lib +and +.Pa /usr/lib . +A library has the following naming convention: +.Bd -unfilled -offset indent +libc.so.7 +.Ed +.Pp +Libraries with an +.Sq .a +suffix are static. +When a program is linked against a static library, all necessary library code +will be included in the binary. +This means the binary can be run even when the libraries are unavailable. +However, it can be inefficient with both disk space and memory usage +during execution. +The C compiler, +.Xr cc 1 , +can be instructed to link statically by specifying the +.Fl static +flag. +.Pp +Libraries with a +.Sq .so.X +suffix are dynamic libraries. +When code is linked dynamically, the library code that the application needs +is not included in the binary. +Instead, data structures are added containing information about which dynamic +libraries to link with. +When the binary is executed, the run-time linker +.Xr ld.so 1 +reads these data structures and loads them into the +process virtual address space. +.Xr rtld 1 +loads the shared libraries when the program is executed. +.Pp +.Sq X +represents the library version number of the library. +In the example above, a binary linked with +.Pa libc.so.8 +would not be usable on a system where only +.Pa libc.so.7 +is available. +.Pp +The advantages of dynamic libraries are that multiple instances of the same +library can share address space, and the physical size of the binary is +smaller. +A namespace per shared library is available via hidden visibility, +allowing multiple compilation units in a library to share things without +making them available to other libraries. +It is possible to load libraries dynamically via +.Xr dlopen 3 . +The disadvantage is the added complexity that comes with loading the +libraries dynamically, and the extra time taken to load the libraries. +Of course, if the libraries are not available, the binary will be unable +to execute. +Calls across shared libraries are also slightly slower and cannot be +inlined, not even with link time optimization. +The C compiler, +.Xr cc 1 , +can be instructed to link dynamically by specifying the +.Fl shared +flag. +.Pp +Shared libraries, as well as static libraries on architectures which produce +position-independent executables +.Pq PIEs +by default, contain position-independent code +.Pq PIC . +Normally, compilers produce relocatable code. +Relocatable code needs to be modified at run-time, depending on where in +memory it is to be run. +The C compiler, +.Xr cc 1 , +can be instructed to generate PIC code by specifying the +.Fl fPIC +flag. +.Pp +Static libraries are generated using the +.Xr ar 1 +utility. +The libraries contain an index to the contents of the library, +stored within the library itself. +The index lists each symbol defined by a member of a library that is a +relocatable object file. +This speeds up linking to the library, and allows routines in the library +to call each other regardless of their placement within the library. .Sh SEE ALSO +.Xr ar 1 , .Xr cc 1 , .Xr ld 1 , .Xr nm 1 , .Xr intro 2 , .Xr math 3 , -.Xr stdio 3 +.Xr stdio 3 , +.Xr make.conf 5 , +.Xr src.conf 5 .Sh HISTORY An .Nm diff --git a/share/man/man3/makedev.3 b/share/man/man3/makedev.3 index 8ce9c554a094..3c0e176a0621 100644 --- a/share/man/man3/makedev.3 +++ b/share/man/man3/makedev.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd August 3, 2017 .Dt MAKEDEV 3 .Os @@ -99,4 +97,4 @@ macros return numbers whose value can span the complete range of an .Sh SEE ALSO .Xr mknod 2 , .Xr devname 3 , -.Xr devfs 5 +.Xr devfs 4 diff --git a/share/man/man3/offsetof.3 b/share/man/man3/offsetof.3 index ee5958f7b932..f757d58ac53d 100644 --- a/share/man/man3/offsetof.3 +++ b/share/man/man3/offsetof.3 @@ -14,8 +14,6 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.\" $FreeBSD$ -.\" .Dd February 18, 2010 .Dt OFFSETOF 3 .Os diff --git a/share/man/man3/pthread.3 b/share/man/man3/pthread.3 index 6b7b82eb27f5..1cb13981e18c 100644 --- a/share/man/man3/pthread.3 +++ b/share/man/man3/pthread.3 @@ -28,8 +28,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd October 12, 2021 .Dt PTHREAD 3 .Os diff --git a/share/man/man3/pthread_affinity_np.3 b/share/man/man3/pthread_affinity_np.3 index 0a52add2ee3c..86c43d2255b9 100644 --- a/share/man/man3/pthread_affinity_np.3 +++ b/share/man/man3/pthread_affinity_np.3 @@ -22,9 +22,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" -.Dd October 12, 2021 +.Dd January 29, 2023 .Dt PTHREAD_AFFINITY_NP 3 .Os .Sh NAME @@ -50,14 +48,19 @@ Masks of type are composed using the .Dv CPU_SET macros. -The kernel tolerates large sets as long as all CPUs specified -in the set exist. -Sets smaller than the kernel uses generate an error on calls to +If the user-supplied mask is not large enough to fit all of the matching CPUs, .Fn pthread_getaffinity_np -even if the result set would fit within the user supplied set. +fails with +.Er ERANGE . Calls to .Fn pthread_setaffinity_np -tolerate small sets with no restrictions. +tolerate masks of any size with no restrictions. +The kernel uses the meaningful part of the mask, where the upper bound is +the maximum CPU id present in the system. +If bits for non-existing CPUs are set, calls to +.Fn pthread_setaffinity_np +fail with +.Er EINVAL . .Pp The supplied mask should have a size of .Fa cpusetsize @@ -96,6 +99,12 @@ and .Fn pthread_setaffinity_np functions may fail if: .Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa cpusetp +argument specified when calling +.Fn pthread_setaffinity_np +was not a valid value. .It Bq Er EDEADLK The .Fn pthread_setaffinity_np @@ -112,7 +121,7 @@ argument could not be found. .It Bq Er ERANGE The .Fa cpusetsize -was either preposterously large or smaller than the kernel set size. +was smaller than needed to fit all of the matching CPUs. .It Bq Er EPERM The calling thread did not have the credentials required to complete the operation. diff --git a/share/man/man3/pthread_atfork.3 b/share/man/man3/pthread_atfork.3 index 2e783caccd54..5edec13e9cf5 100644 --- a/share/man/man3/pthread_atfork.3 +++ b/share/man/man3/pthread_atfork.3 @@ -32,8 +32,6 @@ .\" the referee document. The original Standard can be obtained online at .\" http://www.opengroup.org/unix/online.html. .\" -.\" $FreeBSD$ -.\" .Dd June 21, 2004 .Dt PTHREAD_ATFORK 3 .Os diff --git a/share/man/man3/pthread_attr.3 b/share/man/man3/pthread_attr.3 index 6ce889386d5c..828195c260a5 100644 --- a/share/man/man3/pthread_attr.3 +++ b/share/man/man3/pthread_attr.3 @@ -24,8 +24,6 @@ .\" 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 August 17, 2018 .Dt PTHREAD_ATTR 3 .Os diff --git a/share/man/man3/pthread_attr_affinity_np.3 b/share/man/man3/pthread_attr_affinity_np.3 index 2c85aee9ac19..0589213c6171 100644 --- a/share/man/man3/pthread_attr_affinity_np.3 +++ b/share/man/man3/pthread_attr_affinity_np.3 @@ -22,9 +22,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" -.Dd April 27, 2022 +.Dd January 29, 2023 .Dt PTHREAD_ATTR_AFFINITY_NP 3 .Os .Sh NAME @@ -52,17 +50,18 @@ are composed using the .Dv CPU_SET macros. If the user-supplied mask is not large enough to fit all of the matching CPUs, -.Fn cpuset_getaffinity +.Fn pthread_attr_getaffinity_np fails with .Er ERANGE . Calls to -.Fn cpuset_setaffinity +.Fn pthread_attr_setaffinity_np tolerate masks of any size with no restrictions. -The kernel uses the meaningful part of the mask, where the upper bound is +.Fn pthread_attr_setaffinity_np +uses the meaningful part of the mask, where the upper bound is the maximum CPU id present in the system. If bits for non-existing CPUs are set, calls to -.Fn cpuset_setaffinity -fails with +.Fn pthread_attr_setaffinity_np +fail with .Er EINVAL . .Pp The supplied mask should have a size of diff --git a/share/man/man3/pthread_attr_get_np.3 b/share/man/man3/pthread_attr_get_np.3 index 336c3626a27c..07153586c1b2 100644 --- a/share/man/man3/pthread_attr_get_np.3 +++ b/share/man/man3/pthread_attr_get_np.3 @@ -1,5 +1,10 @@ .\" Copyright (c) 2002,2003 Alexey Zelkin <phantom@FreeBSD.org> .\" All rights reserved. +.\" Copyright (c) 2024 The FreeBSD Foundation +.\" +.\" Portions of this documentation were written by Olivier Certner +.\" <olce@FreeBSD.org> at Kumacom SARL under sponsorship from the +.\" FreeBSD Foundation. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -22,14 +27,12 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" -.Dd October 12, 2021 +.Dd January 5, 2024 .Dt PTHREAD_ATTR_GET_NP 3 .Os .Sh NAME .Nm pthread_attr_get_np -.Nd get attributes of existent thread +.Nd get attributes of an existing thread .Sh LIBRARY .Lb libpthread .Sh SYNOPSIS @@ -39,51 +42,54 @@ .Sh DESCRIPTION The .Fn pthread_attr_get_np -function is used to get existent thread's attributes. -Most fields of -.Vt pthread_attr_t -structure are exact values of attributes provided at thread creation -time (as parameter to -.Xr pthread_create 3 -function), except for the stack address. -.Pp -Value returned as -.Fa dst -is supposed to be used in conjunction with -.Fn pthread_attr_get* -functions to retrieve individual values from +function is used to retrieve the attributes of the specified thread into an +existing .Vt pthread_attr_t structure. -Parameter -.Fa dst -should point to allocated memory area big enough to fit this structure. +The attributes' values are the current ones for the target thread, except for +the stack top address if not properly aligned for the architecture, since in +this case its value has been adjusted internally before use. .Pp -It is HIGHLY RECOMMENDED to use +Argument +.Fa dst +must be a pointer to a valid attributes object +.Po +it was initialized at some point by .Xr pthread_attr_init 3 -function to allocate attribute storage. -.Sh IMPLEMENTATION NOTES -The -.Fn pthread_attr_get_np -function will always return a pointer to the thread's real stack address, -regardless of its value in the original attributes structure. +and was not destroyed since then +.Pc . +After a successful call to +.Fn pthread_attr_get_np , +the individual attributes' values can be retrieved as usual via the +corresponding accessor functions as documented in +.Xr pthread_attr 3 . +After a failed call to +.Fn pthread_attr_get_np , +the object pointed to by +.Fa dst +is left unmodified, and can continue to be used as if the failed call never +happened. .Sh RETURN VALUES If successful, .Fn pthread_attr_get_np function returns 0. Otherwise, an error number is returned to indicate the error. .Sh EXAMPLES +This function retrieves the stack size of the thread specified by the +.Fa pid +argument: .Bd -literal size_t -my_thread_stack_size(pthread_t pid) +my_thread_stack_size(pthread_t tid) { - pthread_attr_t attr; - size_t size; + pthread_attr_t attr; + size_t size; - pthread_attr_init(&attr); - pthread_attr_get_np(pid, &attr); - pthread_attr_getstacksize(&attr, &size); - pthread_attr_destroy(&attr); - return(size); + pthread_attr_init(&attr); + pthread_attr_get_np(tid, &attr); + pthread_attr_getstacksize(&attr, &size); + pthread_attr_destroy(&attr); + return (size); } .Ed .Sh ERRORS @@ -92,12 +98,16 @@ The function will fail if: .Bl -tag -width Er .It Bq Er EINVAL -Invalid value for one of given parameters. +One of the arguments has an invalid value. .It Bq Er ESRCH No thread could be found corresponding to that specified by the given thread ID. +.It Bq Er ENOMEM +There was not enough memory to allocate additional storage needed by the attributes +object's implementation. .El .Sh SEE ALSO +.Xr pthread_attr 3 , .Xr pthread_attr_destroy 3 , .Xr pthread_attr_getdetachstate 3 , .Xr pthread_attr_getinheritsched 3 , @@ -113,4 +123,6 @@ thread ID. The .Fn pthread_attr_get_np function and this manual page were written by -.An Alexey Zelkin Aq Mt phantom@FreeBSD.org . +.An Alexey Zelkin Aq Mt phantom@FreeBSD.org , +and the latter was revised by +.An Olivier Certner Aq Mt olce@FreeBSD.org . diff --git a/share/man/man3/pthread_attr_setcreatesuspend_np.3 b/share/man/man3/pthread_attr_setcreatesuspend_np.3 index d2c6a6f74694..3d2f84a4ad46 100644 --- a/share/man/man3/pthread_attr_setcreatesuspend_np.3 +++ b/share/man/man3/pthread_attr_setcreatesuspend_np.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd October 12, 2021 .Dt PTHREAD_ATTR_SETCREATESUSPEND_NP 3 .Os diff --git a/share/man/man3/pthread_barrier_destroy.3 b/share/man/man3/pthread_barrier_destroy.3 index fbbf88c00e9b..06c8b97e81ed 100644 --- a/share/man/man3/pthread_barrier_destroy.3 +++ b/share/man/man3/pthread_barrier_destroy.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd August 17, 2018 .Dt PTHREAD_BARRIER 3 .Os diff --git a/share/man/man3/pthread_barrierattr.3 b/share/man/man3/pthread_barrierattr.3 index 3836186ef4fd..1f5243f99873 100644 --- a/share/man/man3/pthread_barrierattr.3 +++ b/share/man/man3/pthread_barrierattr.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd August 17, 2018 .Dt PTHREAD_BARRIERATTR 3 .Os diff --git a/share/man/man3/pthread_cancel.3 b/share/man/man3/pthread_cancel.3 index e737f5e36429..33a00300cd65 100644 --- a/share/man/man3/pthread_cancel.3 +++ b/share/man/man3/pthread_cancel.3 @@ -1,4 +1,3 @@ -.\" $FreeBSD$ .Dd January 17, 1999 .Dt PTHREAD_CANCEL 3 .Os diff --git a/share/man/man3/pthread_cleanup_pop.3 b/share/man/man3/pthread_cleanup_pop.3 index 2b7756a24903..2747624b0947 100644 --- a/share/man/man3/pthread_cleanup_pop.3 +++ b/share/man/man3/pthread_cleanup_pop.3 @@ -25,8 +25,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd October 25, 2014 .Dt PTHREAD_CLEANUP_POP 3 .Os diff --git a/share/man/man3/pthread_cleanup_push.3 b/share/man/man3/pthread_cleanup_push.3 index 47f35db98d8a..327c2fc3ce59 100644 --- a/share/man/man3/pthread_cleanup_push.3 +++ b/share/man/man3/pthread_cleanup_push.3 @@ -25,8 +25,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd October 25, 2014 .Dt PTHREAD_CLEANUP_PUSH 3 .Os diff --git a/share/man/man3/pthread_cond_broadcast.3 b/share/man/man3/pthread_cond_broadcast.3 index bbd274103ac3..77c1a2c2b216 100644 --- a/share/man/man3/pthread_cond_broadcast.3 +++ b/share/man/man3/pthread_cond_broadcast.3 @@ -25,8 +25,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd July 28, 1998 .Dt PTHREAD_COND_BROADCAST 3 .Os diff --git a/share/man/man3/pthread_cond_destroy.3 b/share/man/man3/pthread_cond_destroy.3 index 4ea7a87d8a26..ec07b030c1dd 100644 --- a/share/man/man3/pthread_cond_destroy.3 +++ b/share/man/man3/pthread_cond_destroy.3 @@ -25,8 +25,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd July 28, 1998 .Dt PTHREAD_COND_DESTROY 3 .Os diff --git a/share/man/man3/pthread_cond_init.3 b/share/man/man3/pthread_cond_init.3 index 8f13a34fd759..8d3dd79db42d 100644 --- a/share/man/man3/pthread_cond_init.3 +++ b/share/man/man3/pthread_cond_init.3 @@ -25,8 +25,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd August 17, 2018 .Dt PTHREAD_COND_INIT 3 .Os diff --git a/share/man/man3/pthread_cond_signal.3 b/share/man/man3/pthread_cond_signal.3 index 8ab801f91997..5eb656500ddb 100644 --- a/share/man/man3/pthread_cond_signal.3 +++ b/share/man/man3/pthread_cond_signal.3 @@ -25,8 +25,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd July 28, 1998 .Dt PTHREAD_COND_SIGNAL 3 .Os diff --git a/share/man/man3/pthread_cond_timedwait.3 b/share/man/man3/pthread_cond_timedwait.3 index 071f690be195..d955bf8546cd 100644 --- a/share/man/man3/pthread_cond_timedwait.3 +++ b/share/man/man3/pthread_cond_timedwait.3 @@ -25,8 +25,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd May 9, 2010 .Dt PTHREAD_COND_TIMEDWAIT 3 .Os diff --git a/share/man/man3/pthread_cond_wait.3 b/share/man/man3/pthread_cond_wait.3 index 9fcbc2267fd9..c09e7aa68738 100644 --- a/share/man/man3/pthread_cond_wait.3 +++ b/share/man/man3/pthread_cond_wait.3 @@ -25,8 +25,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd August 7, 2019 .Dt PTHREAD_COND_WAIT 3 .Os diff --git a/share/man/man3/pthread_condattr.3 b/share/man/man3/pthread_condattr.3 index b2f14c5452d0..33ad904f9a3d 100644 --- a/share/man/man3/pthread_condattr.3 +++ b/share/man/man3/pthread_condattr.3 @@ -24,9 +24,7 @@ .\" 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 May 31, 2016 +.Dd October 27, 2023 .Dt PTHREAD_CONDATTR 3 .Os .Sh NAME @@ -54,7 +52,7 @@ .Ft int .Fo pthread_condattr_getpshared .Fa "pthread_condattr_t * restrict attr" "int * restrict pshared" -.Fc +.Fc .Ft int .Fn pthread_condattr_setpshared "pthread_condattr_t *attr" "int pshared" .Sh DESCRIPTION @@ -87,7 +85,8 @@ in .Xr pthread_cond_timedwait 3 and may be set to .Dv CLOCK_REALTIME -(default) +(default), +.Dv CLOCK_TAI , or .Dv CLOCK_MONOTONIC . .Pp @@ -114,6 +113,10 @@ threads in the same process as the one that created the object. The condition variable it is attached to may be accessed by threads in processes other than the one that created the object. .El +See +.Xr libthr 3 +for details of the implementation of shared condition variables, +and their limitations. .Sh RETURN VALUES If successful, these functions return 0. Otherwise, an error number is returned to indicate the error. @@ -155,6 +158,7 @@ The value specified in is not one of the allowed values. .El .Sh SEE ALSO +.Xr libthr 3 , .Xr pthread_cond_init 3 , .Xr pthread_cond_timedwait 3 .Sh STANDARDS diff --git a/share/man/man3/pthread_create.3 b/share/man/man3/pthread_create.3 index 3cb7760e26bc..2d43ac7b2ef9 100644 --- a/share/man/man3/pthread_create.3 +++ b/share/man/man3/pthread_create.3 @@ -28,8 +28,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd August 17, 2018 .Dt PTHREAD_CREATE 3 .Os diff --git a/share/man/man3/pthread_detach.3 b/share/man/man3/pthread_detach.3 index dba4aec433c1..93bead1c86cb 100644 --- a/share/man/man3/pthread_detach.3 +++ b/share/man/man3/pthread_detach.3 @@ -28,8 +28,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd April 4, 1996 .Dt PTHREAD_DETACH 3 .Os diff --git a/share/man/man3/pthread_equal.3 b/share/man/man3/pthread_equal.3 index 1ed85319b961..6ef861bc016e 100644 --- a/share/man/man3/pthread_equal.3 +++ b/share/man/man3/pthread_equal.3 @@ -28,8 +28,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd April 4, 1996 .Dt PTHREAD_EQUAL 3 .Os diff --git a/share/man/man3/pthread_exit.3 b/share/man/man3/pthread_exit.3 index f50947112c17..5c8f6ac44f51 100644 --- a/share/man/man3/pthread_exit.3 +++ b/share/man/man3/pthread_exit.3 @@ -28,8 +28,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd March 15, 2014 .Dt PTHREAD_EXIT 3 .Os diff --git a/share/man/man3/pthread_getconcurrency.3 b/share/man/man3/pthread_getconcurrency.3 index c4b23c96dbc5..c94e7b9ed17b 100644 --- a/share/man/man3/pthread_getconcurrency.3 +++ b/share/man/man3/pthread_getconcurrency.3 @@ -21,8 +21,6 @@ .\" 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 11, 2003 .Dt PTHREAD_GETCONCURRENCY 3 .Os diff --git a/share/man/man3/pthread_getcpuclockid.3 b/share/man/man3/pthread_getcpuclockid.3 index c36be81e58dc..b372d2dfeab7 100644 --- a/share/man/man3/pthread_getcpuclockid.3 +++ b/share/man/man3/pthread_getcpuclockid.3 @@ -32,8 +32,6 @@ .\" the referee document. The original Standard can be obtained online at .\" http://www.opengroup.org/unix/online.html. .\" -.\" $FreeBSD$ -.\" .Dd August 21, 2012 .Dt PTHREAD_GETCPUCLOCKID 3 .Os diff --git a/share/man/man3/pthread_getspecific.3 b/share/man/man3/pthread_getspecific.3 index 3657e13515f4..c9a46729a918 100644 --- a/share/man/man3/pthread_getspecific.3 +++ b/share/man/man3/pthread_getspecific.3 @@ -28,8 +28,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd April 4, 1996 .Dt PTHREAD_GETSPECIFIC 3 .Os diff --git a/share/man/man3/pthread_getthreadid_np.3 b/share/man/man3/pthread_getthreadid_np.3 index 562f6a7ae91a..da7ae5455e6f 100644 --- a/share/man/man3/pthread_getthreadid_np.3 +++ b/share/man/man3/pthread_getthreadid_np.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd October 12, 2021 .Dt PTHREAD_GETTHREADID_NP 3 .Os diff --git a/share/man/man3/pthread_join.3 b/share/man/man3/pthread_join.3 index 4cd04eade0aa..716b171e1295 100644 --- a/share/man/man3/pthread_join.3 +++ b/share/man/man3/pthread_join.3 @@ -28,8 +28,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd October 12, 2021 .Dt PTHREAD_JOIN 3 .Os diff --git a/share/man/man3/pthread_key_create.3 b/share/man/man3/pthread_key_create.3 index a818e1a52364..0faf0a07cac5 100644 --- a/share/man/man3/pthread_key_create.3 +++ b/share/man/man3/pthread_key_create.3 @@ -28,8 +28,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd April 4, 1996 .Dt PTHREAD_KEY_CREATE 3 .Os diff --git a/share/man/man3/pthread_key_delete.3 b/share/man/man3/pthread_key_delete.3 index c7861af50ce2..884b261c54fb 100644 --- a/share/man/man3/pthread_key_delete.3 +++ b/share/man/man3/pthread_key_delete.3 @@ -28,8 +28,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd April 4, 1996 .Dt PTHREAD_KEY_DELETE 3 .Os diff --git a/share/man/man3/pthread_kill.3 b/share/man/man3/pthread_kill.3 index 1ef879a2f765..cb2d76c6aa9a 100644 --- a/share/man/man3/pthread_kill.3 +++ b/share/man/man3/pthread_kill.3 @@ -24,8 +24,6 @@ .\" 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 27, 2000 .Dt PTHREAD_KILL 3 .Os diff --git a/share/man/man3/pthread_main_np.3 b/share/man/man3/pthread_main_np.3 index c386cb224a9b..58e3b11dfe66 100644 --- a/share/man/man3/pthread_main_np.3 +++ b/share/man/man3/pthread_main_np.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd October 12, 2021 .Dt PTHREAD_MAIN_NP 3 .Os diff --git a/share/man/man3/pthread_multi_np.3 b/share/man/man3/pthread_multi_np.3 index 065b53c49b1f..62c4fb454fb2 100644 --- a/share/man/man3/pthread_multi_np.3 +++ b/share/man/man3/pthread_multi_np.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd October 12, 2021 .Dt PTHREAD_MULTI_NP 3 .Os diff --git a/share/man/man3/pthread_mutex_consistent.3 b/share/man/man3/pthread_mutex_consistent.3 index ae614f768099..e22be52ba618 100644 --- a/share/man/man3/pthread_mutex_consistent.3 +++ b/share/man/man3/pthread_mutex_consistent.3 @@ -1,4 +1,4 @@ -.\" Copyright (c) 2016 The FreeBSD Foundation, Inc. +.\" Copyright (c) 2016 The FreeBSD Foundation .\" .\" This documentation was written by .\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship @@ -25,8 +25,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd March 27, 2017 .Dt PTHREAD_MUTEX_CONSISTENT 3 .Os diff --git a/share/man/man3/pthread_mutex_destroy.3 b/share/man/man3/pthread_mutex_destroy.3 index d6c4bcd5e446..3627a6c8af8b 100644 --- a/share/man/man3/pthread_mutex_destroy.3 +++ b/share/man/man3/pthread_mutex_destroy.3 @@ -25,8 +25,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd July 29, 1998 .Dt PTHREAD_MUTEX_DESTROY 3 .Os diff --git a/share/man/man3/pthread_mutex_init.3 b/share/man/man3/pthread_mutex_init.3 index 934a323d3a3d..4133cf07713c 100644 --- a/share/man/man3/pthread_mutex_init.3 +++ b/share/man/man3/pthread_mutex_init.3 @@ -25,8 +25,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd August 17, 2018 .Dt PTHREAD_MUTEX_INIT 3 .Os diff --git a/share/man/man3/pthread_mutex_lock.3 b/share/man/man3/pthread_mutex_lock.3 index cd55ef8699af..ba54cd45b99c 100644 --- a/share/man/man3/pthread_mutex_lock.3 +++ b/share/man/man3/pthread_mutex_lock.3 @@ -25,8 +25,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd August 7, 2019 .Dt PTHREAD_MUTEX_LOCK 3 .Os diff --git a/share/man/man3/pthread_mutex_timedlock.3 b/share/man/man3/pthread_mutex_timedlock.3 index 006357659e14..b6e95edbe46e 100644 --- a/share/man/man3/pthread_mutex_timedlock.3 +++ b/share/man/man3/pthread_mutex_timedlock.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd August 7, 2019 .Dt PTHREAD_MUTEX_TIMEDLOCK 3 .Os diff --git a/share/man/man3/pthread_mutex_trylock.3 b/share/man/man3/pthread_mutex_trylock.3 index 131b81653580..cd08d760595a 100644 --- a/share/man/man3/pthread_mutex_trylock.3 +++ b/share/man/man3/pthread_mutex_trylock.3 @@ -25,8 +25,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd August 7, 2019 .Dt PTHREAD_MUTEX_TRYLOCK 3 .Os diff --git a/share/man/man3/pthread_mutex_unlock.3 b/share/man/man3/pthread_mutex_unlock.3 index 4d3badd8aa0e..eb6866a2c90d 100644 --- a/share/man/man3/pthread_mutex_unlock.3 +++ b/share/man/man3/pthread_mutex_unlock.3 @@ -25,8 +25,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd April 29, 2016 .Dt PTHREAD_MUTEX_UNLOCK 3 .Os diff --git a/share/man/man3/pthread_mutexattr.3 b/share/man/man3/pthread_mutexattr.3 index 2a2c5c8d133e..b18d93e2e13e 100644 --- a/share/man/man3/pthread_mutexattr.3 +++ b/share/man/man3/pthread_mutexattr.3 @@ -1,5 +1,5 @@ .\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. -.\" Copyright (c) 2021 The FreeBSD Foundation, Inc. +.\" Copyright (c) 2021 The FreeBSD Foundation .\" All rights reserved. .\" .\" Part of this documentation was written by @@ -29,9 +29,7 @@ .\" 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 1, 2021 +.Dd October 27, 2023 .Dt PTHREAD_MUTEXATTR 3 .Os .Sh NAME @@ -134,6 +132,30 @@ all threads waiting on any mutex owned by this thread. .El .Pp The +.Fn pthread_mutexattr_setpshared +function sets the process-shared attribute of +.Fa attr +to the value specified in +.Fa pshared . +The argument +.Fa pshared +may have one of the following values: +.Bl -tag -width ".Dv PTHREAD_PROCESS_PRIVATE" +.It Dv PTHREAD_PROCESS_PRIVATE +The mutex may only be used by threads in the same process as the one +that created the object. +.It Dv PTHREAD_PROCESS_SHARED +The mutex may be used by +threads in processes other than the one that created the object, +assuming other processes share access to the memory where the mutex +was allocated. +.El +See +.Xr libthr 3 +for details of the implementation of the shared mutexes, +and their limitations. +.Pp +The .Fn pthread_mutexattr_setrobust function specifies robustness attribute of the mutex. Possible values for the @@ -316,6 +338,7 @@ Invalid value for .Fa attr . .El .Sh SEE ALSO +.Xr libthr 3 , .Xr pthread_mutex_init 3 .Sh STANDARDS The diff --git a/share/man/man3/pthread_mutexattr_getkind_np.3 b/share/man/man3/pthread_mutexattr_getkind_np.3 index cc3cc3df20ae..15eb7061b20e 100644 --- a/share/man/man3/pthread_mutexattr_getkind_np.3 +++ b/share/man/man3/pthread_mutexattr_getkind_np.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd October 12, 2021 .Dt PTHREAD_MUTEXATTR_GETKIND_NP 3 .Os diff --git a/share/man/man3/pthread_np.3 b/share/man/man3/pthread_np.3 index caab8cc13209..c6f0efac7415 100644 --- a/share/man/man3/pthread_np.3 +++ b/share/man/man3/pthread_np.3 @@ -116,6 +116,11 @@ Sets the specified thread's name. .Xc Sets the specified thread's name. .It Xo +.Ft void +.Fn pthread_signals_block_np void +.Xc +Blocks all asynchronous signals, quickly. +.It Xo .Ft int .Fn pthread_single_np void .Xc @@ -132,16 +137,6 @@ Suspend the specified thread. Suspend all active threads. .It Xo .Ft int -.Fn pthread_switch_add_np "pthread_switch_routine_t routine" -.Xc -Install a routine that is called every time a thread context switches. -.It Xo -.Ft int -.Fn pthread_switch_delete_np "pthread_switch_routine_t routine" -.Xc -Remove a routine that is called every time a thread context switches. -.It Xo -.Ft int .Fo pthread_timedjoin_np .Fa "pthread_t thread" "void **value_ptr" "const struct timespec *abstime" .Fc @@ -223,6 +218,7 @@ instead. .Xr pthread_resume_all_np 3 , .Xr pthread_resume_np 3 , .Xr pthread_set_name_np 3 , +.Xr pthread_signals_block_np 3 , .Xr pthread_suspend_all_np 3 , .Xr pthread_suspend_np 3 , .Xr pthread_switch_add_np 3 diff --git a/share/man/man3/pthread_once.3 b/share/man/man3/pthread_once.3 index fe234187730c..1ff0a74bc1c2 100644 --- a/share/man/man3/pthread_once.3 +++ b/share/man/man3/pthread_once.3 @@ -28,8 +28,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd April 4, 1996 .Dt PTHREAD_ONCE 3 .Os diff --git a/share/man/man3/pthread_resume_all_np.3 b/share/man/man3/pthread_resume_all_np.3 index 40df03a07af1..411d5a570f4b 100644 --- a/share/man/man3/pthread_resume_all_np.3 +++ b/share/man/man3/pthread_resume_all_np.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd October 12, 2021 .Dt PTHREAD_RESUME_ALL_NP 3 .Os diff --git a/share/man/man3/pthread_resume_np.3 b/share/man/man3/pthread_resume_np.3 index 16833872c010..546e133657b6 100644 --- a/share/man/man3/pthread_resume_np.3 +++ b/share/man/man3/pthread_resume_np.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd October 12, 2021 .Dt PTHREAD_RESUME_NP 3 .Os diff --git a/share/man/man3/pthread_rwlock_destroy.3 b/share/man/man3/pthread_rwlock_destroy.3 index 0129222866b2..9c50e71fea81 100644 --- a/share/man/man3/pthread_rwlock_destroy.3 +++ b/share/man/man3/pthread_rwlock_destroy.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd August 4, 1998 .Dt PTHREAD_RWLOCK_DESTROY 3 .Os diff --git a/share/man/man3/pthread_rwlock_init.3 b/share/man/man3/pthread_rwlock_init.3 index 3b99032889d8..e6474199c564 100644 --- a/share/man/man3/pthread_rwlock_init.3 +++ b/share/man/man3/pthread_rwlock_init.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd August 17, 2018 .Dt PTHREAD_RWLOCK_INIT 3 .Os diff --git a/share/man/man3/pthread_rwlock_rdlock.3 b/share/man/man3/pthread_rwlock_rdlock.3 index 7a197f210ba0..f8403fc8f279 100644 --- a/share/man/man3/pthread_rwlock_rdlock.3 +++ b/share/man/man3/pthread_rwlock_rdlock.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd August 4, 1998 .Dt PTHREAD_RWLOCK_RDLOCK 3 .Os diff --git a/share/man/man3/pthread_rwlock_timedrdlock.3 b/share/man/man3/pthread_rwlock_timedrdlock.3 index 2f012f516c1f..2b7365298323 100644 --- a/share/man/man3/pthread_rwlock_timedrdlock.3 +++ b/share/man/man3/pthread_rwlock_timedrdlock.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd August 17, 2018 .Dt PTHREAD_RWLOCK_TIMEDRDLOCK 3 .Os diff --git a/share/man/man3/pthread_rwlock_timedwrlock.3 b/share/man/man3/pthread_rwlock_timedwrlock.3 index 041c0e54cd46..4543eff46d92 100644 --- a/share/man/man3/pthread_rwlock_timedwrlock.3 +++ b/share/man/man3/pthread_rwlock_timedwrlock.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd August 17, 2018 .Dt PTHREAD_RWLOCK_TIMEDWRLOCK 3 .Os diff --git a/share/man/man3/pthread_rwlock_unlock.3 b/share/man/man3/pthread_rwlock_unlock.3 index 8ad891ea4545..8e348e927a29 100644 --- a/share/man/man3/pthread_rwlock_unlock.3 +++ b/share/man/man3/pthread_rwlock_unlock.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd August 4, 1998 .Dt PTHREAD_RWLOCK_UNLOCK 3 .Os diff --git a/share/man/man3/pthread_rwlock_wrlock.3 b/share/man/man3/pthread_rwlock_wrlock.3 index 602b54fd029f..58416b27de64 100644 --- a/share/man/man3/pthread_rwlock_wrlock.3 +++ b/share/man/man3/pthread_rwlock_wrlock.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd August 4, 1998 .Dt PTHREAD_RWLOCK_WRLOCK 3 .Os diff --git a/share/man/man3/pthread_rwlockattr_destroy.3 b/share/man/man3/pthread_rwlockattr_destroy.3 index bff808fdbbd9..eabfbad7e0f2 100644 --- a/share/man/man3/pthread_rwlockattr_destroy.3 +++ b/share/man/man3/pthread_rwlockattr_destroy.3 @@ -22,14 +22,12 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd August 4, 1998 .Dt PTHREAD_RWLOCKATTR_DESTROY 3 .Os .Sh NAME .Nm pthread_rwlockattr_destroy -.Nd destroy a read/write lock +.Nd destroy a read/write lock attributes object .Sh LIBRARY .Lb libpthread .Sh SYNOPSIS @@ -39,7 +37,7 @@ .Sh DESCRIPTION The .Fn pthread_rwlockattr_destroy -function is used to destroy a read/write lock attribute object +function is used to destroy a read/write lock attributes object previously created with .Fn pthread_rwlockattr_init . .Sh RETURN VALUES diff --git a/share/man/man3/pthread_rwlockattr_getpshared.3 b/share/man/man3/pthread_rwlockattr_getpshared.3 index 8e65be3ce391..33d7cd3229f0 100644 --- a/share/man/man3/pthread_rwlockattr_getpshared.3 +++ b/share/man/man3/pthread_rwlockattr_getpshared.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd August 17, 2018 .Dt PTHREAD_RWLOCKATTR_GETPSHARED 3 .Os diff --git a/share/man/man3/pthread_rwlockattr_init.3 b/share/man/man3/pthread_rwlockattr_init.3 index 1cce9cd02554..031d010ae81a 100644 --- a/share/man/man3/pthread_rwlockattr_init.3 +++ b/share/man/man3/pthread_rwlockattr_init.3 @@ -22,14 +22,12 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd August 4, 1998 .Dt PTHREAD_RWLOCKATTR_INIT 3 .Os .Sh NAME .Nm pthread_rwlockattr_init -.Nd initialize a read/write lock +.Nd initialize a read/write lock attributes object .Sh LIBRARY .Lb libpthread .Sh SYNOPSIS @@ -52,7 +50,7 @@ The function will fail if: .Bl -tag -width Er .It Bq Er ENOMEM -Insufficient memory exists to initialize the attribute object. +Insufficient memory exists to initialize the attributes object. .El .Sh SEE ALSO .Xr pthread_rwlock_init 3 , diff --git a/share/man/man3/pthread_rwlockattr_setpshared.3 b/share/man/man3/pthread_rwlockattr_setpshared.3 index bf2ddac0285a..3ed86f411ef4 100644 --- a/share/man/man3/pthread_rwlockattr_setpshared.3 +++ b/share/man/man3/pthread_rwlockattr_setpshared.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd May 31, 2016 .Dt PTHREAD_RWLOCKATTR_SETPSHARED 3 .Os diff --git a/share/man/man3/pthread_schedparam.3 b/share/man/man3/pthread_schedparam.3 index 9d8b98a89d96..3ba175781f48 100644 --- a/share/man/man3/pthread_schedparam.3 +++ b/share/man/man3/pthread_schedparam.3 @@ -25,9 +25,7 @@ .\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" -.Dd August 17, 2018 +.Dd October 17, 2022 .Dt PTHREAD_SCHEDPARAM 3 .Os .Sh NAME @@ -75,6 +73,8 @@ Invalid value for .Fa policy . .It Bq Er ENOTSUP Invalid value for scheduling parameters. +.It Bq Er EPERM +The calling thread does not have sufficient privilege to perform the operation. .It Bq Er ESRCH Non-existent thread .Fa thread . diff --git a/share/man/man3/pthread_self.3 b/share/man/man3/pthread_self.3 index 8b346836c631..1c4853006fb1 100644 --- a/share/man/man3/pthread_self.3 +++ b/share/man/man3/pthread_self.3 @@ -28,8 +28,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd April 4, 1996 .Dt PTHREAD_SELF 3 .Os diff --git a/share/man/man3/pthread_set_name_np.3 b/share/man/man3/pthread_set_name_np.3 index 5423ef898f58..69adcad2bd81 100644 --- a/share/man/man3/pthread_set_name_np.3 +++ b/share/man/man3/pthread_set_name_np.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd October 12, 2021 .Dt PTHREAD_SET_NAME_NP 3 .Os diff --git a/share/man/man3/pthread_setspecific.3 b/share/man/man3/pthread_setspecific.3 index 3153c991f90b..59079e35890d 100644 --- a/share/man/man3/pthread_setspecific.3 +++ b/share/man/man3/pthread_setspecific.3 @@ -28,8 +28,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd April 4, 1996 .Dt PTHREAD_SETSPECIFIC 3 .Os diff --git a/share/man/man3/pthread_sigmask.3 b/share/man/man3/pthread_sigmask.3 index 013ba7cb6844..8d2a5d6519d5 100644 --- a/share/man/man3/pthread_sigmask.3 +++ b/share/man/man3/pthread_sigmask.3 @@ -24,8 +24,6 @@ .\" 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 February 19, 2011 .Dt PTHREAD_SIGMASK 3 .Os diff --git a/share/man/man3/pthread_signals_block_np.3 b/share/man/man3/pthread_signals_block_np.3 new file mode 100644 index 000000000000..de33f4e6189e --- /dev/null +++ b/share/man/man3/pthread_signals_block_np.3 @@ -0,0 +1,81 @@ +.\" Copyright (c) 2025 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.Dd May 16, 2025 +.Dt PTHREAD_SIGNALS_BLOCK_NP 3 +.Os +.Sh NAME +.Nm pthread_signals_block_np , +.Nm pthread_signals_unblock_np +.Nd fast asynchronous signals blocking and unblocking +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft void +.Fn pthread_signals_block_np "void" +.Ft void +.Fn pthread_signals_unblock_np "void" +.Sh DESCRIPTION +The +.Fn pthread_signals_block_np +and +.Fn pthread_signals_unblock_np +functions provide user programs an interface to the fast asynchronous +signals blocking facility +.Xr sigfastblock 2 . +.Pp +Blocking signals with +.Fn pthread_signals_block_np +disables delivery of any asynchronous signal, until unblocked. +Signal blocking establishes a critical section where the execution +flow of the thread cannot be diverted into a signal handler. +Blocking signals is fast, it is performed by a single memory write into +a location established with the kernel. +.Pp +Synchronous signal delivery cannot be blocked in general, including with +these functions. +.Pp +The blocked state established by the +.Fn pthread_signals_block_np +is not completely POSIX-compliant. +Specifically, system calls executed while in a blocked section, +might abort sleep and return +.Er EINTR +upon queuing of an asynchronous signal to the thread, +but the signal handler is not called until the last unblock is done. +.Pp +Calls to +.Nm pthread_signals_block_np +can be nested, and must be complemented by an equal count of +calls to +.Nm pthread_signals_unblock_np +to return the calling thread to the standard mode of signal receiving. +.Pp +An example use of these function might be the construction of the CPU +state that cannot be done atomically, and which includes stages where +the state of the thread is not ABI compliant. +If a signal is delivered while such state is not yet finished, signal +handlers would misbehave. +Using standard functions +.Pq Fn sigprocmask +to establish critical section might be much slower, because +.Fn sigprocmask +is system call, while +.Fn pthread_signals_block_np +consists of a single atomic memory write. +.Sh RETURN VALUES +The functions do not return a value. +.Sh ERRORS +There are no errors reported by the functions. +.Sh SEE ALSO +.Xr sigfastblock 2 , +.Xr sigprocmask 2 , +.Xr pthread_sigmask 3 , +.Xr pthread_np 3 diff --git a/share/man/man3/pthread_sigqueue.3 b/share/man/man3/pthread_sigqueue.3 new file mode 100644 index 000000000000..852f6314e9d0 --- /dev/null +++ b/share/man/man3/pthread_sigqueue.3 @@ -0,0 +1,102 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright 2024 The FreeBSD Foundation +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" 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(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) 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, 2024 +.Dt PTHREAD_SIGQUEUE 3 +.Os +.Sh NAME +.Nm pthread_sigqueue +.Nd queue a signal to a specified thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.In signal.h +.Ft int +.Fn pthread_sigqueue "pthread_t thread" "int sig" "const union sigval value" +.Sh DESCRIPTION +The +.Fn pthread_queue +function queues a signal, specified by +.Fa sig , +to a thread, specified by +.Fa thread . +If +.Fa sig +is 0, error checking is performed, but no signal is actually sent. +The +.Fa value +is queued together with the signal, and becomes available in +.Vt siginfo_t +data passed to the signal handler. +.Pp +The +.Nm +function is similar to +.Xr sigqueue 2 , +but targets a thread in the current process instead of a process. +See +.Xr sigqueue 2 +for details about signal queueing and delivery selection. +.Sh RETURN VALUES +If successful, +.Fn pthread_sigqueue +returns 0. +Otherwise, an error number is returned. +.Sh ERRORS +The +.Fn pthread_sigqueue +function will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +No resources are available to queue the signal. +The current process has already queued +.Brq Dv SIGQUEUE_MAX +signals that are still pending, +or a system-wide resource limit has been exceeded. +.It Bq Er ESRCH +.Fa thread +is an invalid thread ID. +.It Bq Er EINVAL +.Fa sig +is an invalid or unsupported signal number. +.El +.Sh SEE ALSO +.Xr sigqueue 2 +.Sh STANDARDS +The +.Fn pthread_sigqueue +function is a +.Fx +extension. +An identical function with the same semantic is available in other +operating systems. diff --git a/share/man/man3/pthread_spin_init.3 b/share/man/man3/pthread_spin_init.3 index 3ef67add5248..4820ddcf7885 100644 --- a/share/man/man3/pthread_spin_init.3 +++ b/share/man/man3/pthread_spin_init.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd May 31, 2016 .Dt PTHREAD_SPIN_INIT 3 .Os diff --git a/share/man/man3/pthread_spin_lock.3 b/share/man/man3/pthread_spin_lock.3 index 24dea92d2397..4308271a384f 100644 --- a/share/man/man3/pthread_spin_lock.3 +++ b/share/man/man3/pthread_spin_lock.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd January 22, 2004 .Dt PTHREAD_SPIN_LOCK 3 .Os diff --git a/share/man/man3/pthread_suspend_all_np.3 b/share/man/man3/pthread_suspend_all_np.3 index 2821c7360786..c99a08a05b6c 100644 --- a/share/man/man3/pthread_suspend_all_np.3 +++ b/share/man/man3/pthread_suspend_all_np.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd October 12, 2021 .Dt PTHREAD_SUSPEND_ALL_NP 3 .Os diff --git a/share/man/man3/pthread_suspend_np.3 b/share/man/man3/pthread_suspend_np.3 index 58bcf56964b6..8e05bac0d985 100644 --- a/share/man/man3/pthread_suspend_np.3 +++ b/share/man/man3/pthread_suspend_np.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd October 12, 2021 .Dt PTHREAD_SUSPEND_NP 3 .Os diff --git a/share/man/man3/pthread_switch_add_np.3 b/share/man/man3/pthread_switch_add_np.3 deleted file mode 100644 index ddfa630ffd9a..000000000000 --- a/share/man/man3/pthread_switch_add_np.3 +++ /dev/null @@ -1,88 +0,0 @@ -.\" Copyright (c) 2003 Alexey Zelkin <phantom@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 October 12, 2021 -.Dt PTHREAD_SWITCH_ADD_NP 3 -.Os -.Sh NAME -.Nm pthread_switch_add_np , -.Nm pthread_switch_delete_np -.Nd thread context switches debugging primitives -.Sh LIBRARY -.Lb libpthread -.Sh SYNOPSIS -.In pthread_np.h -.Ft int -.Fn pthread_switch_add_np "pthread_switch_routine_t routine" -.Ft int -.Fn pthread_switch_delete_np "pthread_switch_routine_t routine" -.Sh DESCRIPTION -An application is allowed to monitor the thread context switches inside -the threading library. -An application can install a routine that gets called every time a thread -(explicitly created by an application with the -.Xr pthread_create 3 -function) gets the context switched. -The routine is passed the thread IDs of the threads that are -being switched in and out. -Installation and removal of these hooks may be done using the -.Fn pthread_switch_add_np -and -.Fn pthread_switch_delete_np -functions respectively. -.Sh RETURN VALUES -If successful, -these functions return 0. -Otherwise, an error number is returned to indicate the error. -.Sh ERRORS -The -.Fn pthread_switch_add_np -may fail if: -.Bl -tag -width Er -.It Bq Er EINVAL -.Dv NULL -pointer was passed in the -.Fa routine -argument. -.El -.Pp -The -.Fn pthread_switch_delete_np -may fail if: -.Bl -tag -width Er -.It Bq Er EINVAL -The -.Fa routine -argument is different from the argument previously passed to the -.Fn pthread_switch_add_np -function. -.El -.Sh SEE ALSO -.Xr pthread_create 3 , -.Xr pthread_np 3 -.Sh AUTHORS -This manual page was written by -.An Alexey Zelkin Aq Mt phantom@FreeBSD.org . diff --git a/share/man/man3/pthread_testcancel.3 b/share/man/man3/pthread_testcancel.3 index 9ba1403dffdc..c74cdcfe943b 100644 --- a/share/man/man3/pthread_testcancel.3 +++ b/share/man/man3/pthread_testcancel.3 @@ -1,4 +1,3 @@ -.\" $FreeBSD$ .Dd March 18, 2017 .Dt PTHREAD_TESTCANCEL 3 .Os @@ -35,6 +34,7 @@ are .Dv PTHREAD_CANCEL_ENABLE and .Dv PTHREAD_CANCEL_DISABLE . +The function is async-signal-safe. .Pp The .Fn pthread_setcanceltype @@ -249,6 +249,11 @@ function conforms to .St -p1003.1-96 . The standard allows implementations to make many more functions cancellation points. +.Pp +The +.Fn pthread_setcancelstate +function is async-signal-safe as required by +.St -p1003.1-2024 . .Sh AUTHORS This manual page was written by .An David Leonard Aq Mt d@openbsd.org diff --git a/share/man/man3/pthread_yield.3 b/share/man/man3/pthread_yield.3 index e47c033acfb7..e9ef649109a7 100644 --- a/share/man/man3/pthread_yield.3 +++ b/share/man/man3/pthread_yield.3 @@ -2,8 +2,6 @@ .\" .\" PUBLIC DOMAIN: No Rights Reserved. Marco S Hyman <marc@snafu.org> .\" -.\" $FreeBSD$ -.\" .Dd September 18, 2006 .Dt PTHREAD_YIELD 3 .Os diff --git a/share/man/man3/qmath.3 b/share/man/man3/qmath.3 index 3e874ab704e6..5c2332f0bc55 100644 --- a/share/man/man3/qmath.3 +++ b/share/man/man3/qmath.3 @@ -23,8 +23,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd July 4, 2019 .Dt QMATH 3 .Os diff --git a/share/man/man3/queue.3 b/share/man/man3/queue.3 index 2e2ddec0c555..535358ae82d5 100644 --- a/share/man/man3/queue.3 +++ b/share/man/man3/queue.3 @@ -25,10 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" @(#)queue.3 8.2 (Berkeley) 1/24/94 -.\" $FreeBSD$ -.\" -.Dd September 8, 2016 +.Dd April 28, 2025 .Dt QUEUE 3 .Os .Sh NAME @@ -36,6 +33,7 @@ .Nm SLIST_CLASS_HEAD , .Nm SLIST_CONCAT , .Nm SLIST_EMPTY , +.Nm SLIST_EMPTY_ATOMIC , .Nm SLIST_ENTRY , .Nm SLIST_FIRST , .Nm SLIST_FOREACH , @@ -51,11 +49,13 @@ .Nm SLIST_REMOVE , .Nm SLIST_REMOVE_AFTER , .Nm SLIST_REMOVE_HEAD , +.Nm SLIST_SPLIT_AFTER , .Nm SLIST_SWAP , .Nm STAILQ_CLASS_ENTRY , .Nm STAILQ_CLASS_HEAD , .Nm STAILQ_CONCAT , .Nm STAILQ_EMPTY , +.Nm STAILQ_EMPTY_ATOMIC , .Nm STAILQ_ENTRY , .Nm STAILQ_FIRST , .Nm STAILQ_FOREACH , @@ -73,11 +73,14 @@ .Nm STAILQ_REMOVE , .Nm STAILQ_REMOVE_AFTER , .Nm STAILQ_REMOVE_HEAD , +.Nm STAILQ_REVERSE , +.Nm STAILQ_SPLIT_AFTER , .Nm STAILQ_SWAP , .Nm LIST_CLASS_ENTRY , .Nm LIST_CLASS_HEAD , .Nm LIST_CONCAT , .Nm LIST_EMPTY , +.Nm LIST_EMPTY_ATOMIC , .Nm LIST_ENTRY , .Nm LIST_FIRST , .Nm LIST_FOREACH , @@ -93,11 +96,14 @@ .Nm LIST_NEXT , .Nm LIST_PREV , .Nm LIST_REMOVE , +.Nm LIST_REPLACE , +.Nm LIST_SPLIT_AFTER , .Nm LIST_SWAP , .Nm TAILQ_CLASS_ENTRY , .Nm TAILQ_CLASS_HEAD , .Nm TAILQ_CONCAT , .Nm TAILQ_EMPTY , +.Nm TAILQ_EMPTY_ATOMIC , .Nm TAILQ_ENTRY , .Nm TAILQ_FIRST , .Nm TAILQ_FOREACH , @@ -119,6 +125,8 @@ .Nm TAILQ_NEXT , .Nm TAILQ_PREV , .Nm TAILQ_REMOVE , +.Nm TAILQ_REPLACE , +.Nm TAILQ_SPLIT_AFTER , .Nm TAILQ_SWAP .Nd implementations of singly-linked lists, singly-linked tail queues, lists and tail queues @@ -129,6 +137,7 @@ lists and tail queues .Fn SLIST_CLASS_HEAD "HEADNAME" "CLASSTYPE" .Fn SLIST_CONCAT "SLIST_HEAD *head1" "SLIST_HEAD *head2" "TYPE" "SLIST_ENTRY NAME" .Fn SLIST_EMPTY "SLIST_HEAD *head" +.Fn SLIST_EMPTY_ATOMIC "SLIST_HEAD *head" .Fn SLIST_ENTRY "TYPE" .Fn SLIST_FIRST "SLIST_HEAD *head" .Fn SLIST_FOREACH "TYPE *var" "SLIST_HEAD *head" "SLIST_ENTRY NAME" @@ -144,12 +153,14 @@ lists and tail queues .Fn SLIST_REMOVE "SLIST_HEAD *head" "TYPE *elm" "TYPE" "SLIST_ENTRY NAME" .Fn SLIST_REMOVE_AFTER "TYPE *elm" "SLIST_ENTRY NAME" .Fn SLIST_REMOVE_HEAD "SLIST_HEAD *head" "SLIST_ENTRY NAME" +.Fn SLIST_SPLIT_AFTER "SLIST_HEAD *head" "TYPE *elm" "SLIST_HEAD *rest" "SLIST_ENTRY NAME" .Fn SLIST_SWAP "SLIST_HEAD *head1" "SLIST_HEAD *head2" "TYPE" .\" .Fn STAILQ_CLASS_ENTRY "CLASSTYPE" .Fn STAILQ_CLASS_HEAD "HEADNAME" "CLASSTYPE" .Fn STAILQ_CONCAT "STAILQ_HEAD *head1" "STAILQ_HEAD *head2" .Fn STAILQ_EMPTY "STAILQ_HEAD *head" +.Fn STAILQ_EMPTY_ATOMIC "STAILQ_HEAD *head" .Fn STAILQ_ENTRY "TYPE" .Fn STAILQ_FIRST "STAILQ_HEAD *head" .Fn STAILQ_FOREACH "TYPE *var" "STAILQ_HEAD *head" "STAILQ_ENTRY NAME" @@ -167,12 +178,15 @@ lists and tail queues .Fn STAILQ_REMOVE "STAILQ_HEAD *head" "TYPE *elm" "TYPE" "STAILQ_ENTRY NAME" .Fn STAILQ_REMOVE_AFTER "STAILQ_HEAD *head" "TYPE *elm" "STAILQ_ENTRY NAME" .Fn STAILQ_REMOVE_HEAD "STAILQ_HEAD *head" "STAILQ_ENTRY NAME" +.Fn STAILQ_REVERSE "STAILQ_HEAD *head" "TYPE" "STAILQ_ENTRY NAME" +.Fn STAILQ_SPLIT_AFTER "STAILQ_HEAD *head" "TYPE *elm" "STAILQ_HEAD *rest" "STAILQ_ENTRY NAME" .Fn STAILQ_SWAP "STAILQ_HEAD *head1" "STAILQ_HEAD *head2" "TYPE" .\" .Fn LIST_CLASS_ENTRY "CLASSTYPE" .Fn LIST_CLASS_HEAD "HEADNAME" "CLASSTYPE" .Fn LIST_CONCAT "LIST_HEAD *head1" "LIST_HEAD *head2" "TYPE" "LIST_ENTRY NAME" .Fn LIST_EMPTY "LIST_HEAD *head" +.Fn LIST_EMPTY_ATOMIC "LIST_HEAD *head" .Fn LIST_ENTRY "TYPE" .Fn LIST_FIRST "LIST_HEAD *head" .Fn LIST_FOREACH "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" @@ -188,12 +202,15 @@ lists and tail queues .Fn LIST_NEXT "TYPE *elm" "LIST_ENTRY NAME" .Fn LIST_PREV "TYPE *elm" "LIST_HEAD *head" "TYPE" "LIST_ENTRY NAME" .Fn LIST_REMOVE "TYPE *elm" "LIST_ENTRY NAME" +.Fn LIST_REPLACE "TYPE *elm" "TYPE *new" "LIST_ENTRY NAME" +.Fn LIST_SPLIT_AFTER "LIST_HEAD *head" "TYPE *elm" "LIST_HEAD *rest" "LIST_ENTRY NAME" .Fn LIST_SWAP "LIST_HEAD *head1" "LIST_HEAD *head2" "TYPE" "LIST_ENTRY NAME" .\" .Fn TAILQ_CLASS_ENTRY "CLASSTYPE" .Fn TAILQ_CLASS_HEAD "HEADNAME" "CLASSTYPE" .Fn TAILQ_CONCAT "TAILQ_HEAD *head1" "TAILQ_HEAD *head2" "TAILQ_ENTRY NAME" .Fn TAILQ_EMPTY "TAILQ_HEAD *head" +.Fn TAILQ_EMPTY_ATOMIC "TAILQ_HEAD *head" .Fn TAILQ_ENTRY "TYPE" .Fn TAILQ_FIRST "TAILQ_HEAD *head" .Fn TAILQ_FOREACH "TYPE *var" "TAILQ_HEAD *head" "TAILQ_ENTRY NAME" @@ -215,6 +232,8 @@ lists and tail queues .Fn TAILQ_NEXT "TYPE *elm" "TAILQ_ENTRY NAME" .Fn TAILQ_PREV "TYPE *elm" "HEADNAME" "TAILQ_ENTRY NAME" .Fn TAILQ_REMOVE "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME" +.Fn TAILQ_REPLACE "TAILQ_HEAD *head" "TYPE *elm" "TYPE *new" "TAILQ_ENTRY NAME" +.Fn TAILQ_SPLIT_AFTER "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_HEAD *rest" "TAILQ_ENTRY NAME" .Fn TAILQ_SWAP "TAILQ_HEAD *head1" "TAILQ_HEAD *head2" "TYPE" "TAILQ_ENTRY NAME" .\" .Sh DESCRIPTION @@ -241,6 +260,8 @@ O(1) removal of an entry from the head of the list. .It Forward traversal through the list. .It +Splitting a list in two after any element in the list. +.It Swapping the contents of two lists. .El .Pp @@ -424,6 +445,10 @@ high-usage code paths or to operate on long lists. The macro .Nm SLIST_EMPTY evaluates to true if there are no elements in the list. +The +.Nm SLIST_EMPTY_ATOMIC +variant has the same behavior, but can be safely used in contexts where it is +possible that a different thread is concurrently updating the list. .Pp The macro .Nm SLIST_ENTRY @@ -534,6 +559,17 @@ A doubly-linked list should be used if this macro is needed in high-usage code paths or to operate on long lists. .Pp The macro +.Nm SLIST_SPLIT_AFTER +splits the list referenced by +.Fa head , +making +.Fa rest +reference the list formed by elements after +.Fa elm +in +.Fa head . +.Pp +The macro .Nm SLIST_SWAP swaps the contents of .Fa head1 @@ -632,6 +668,10 @@ removing all entries from the former. The macro .Nm STAILQ_EMPTY evaluates to true if there are no items on the tail queue. +The +.Nm STAILQ_EMPTY_ATOMIC +variant has the same behavior, but can be safely used in contexts where it is +possible that a different thread is concurrently updating the queue. .Pp The macro .Nm STAILQ_ENTRY @@ -753,6 +793,21 @@ A doubly-linked tail queue should be used if this macro is needed in high-usage code paths or to operate on long tail queues. .Pp The macro +.Nm STAILQ_REVERSE +reverses the queue in place. +.Pp +The macro +.Nm STAILQ_SPLIT_AFTER +splits the tail queue referenced by +.Fa head , +making +.Fa rest +reference the tail queue formed by elements after +.Fa elm +in +.Fa head . +.Pp +The macro .Nm STAILQ_SWAP swaps the contents of .Fa head1 @@ -865,6 +920,10 @@ high-usage code paths or to operate on long lists. The macro .Nm LIST_EMPTY evaluates to true if there are no elements in the list. +The +.Nm LIST_EMPTY_ATOMIC +variant has the same behavior, but can be safely used in contexts where it is +possible that a different thread is concurrently updating the list. .Pp The macro .Nm LIST_ENTRY @@ -966,6 +1025,28 @@ removes the element from the list. .Pp The macro +.Fn LIST_REPLACE +replaces the element +.Fa elm +with +.Fa new +in the list. +The element +.Fa new +must not already be on a list. +.Pp +The macro +.Nm LIST_SPLIT_AFTER +splits the list referenced by +.Fa head , +making +.Fa rest +reference the list formed by elements after +.Fa elm +in +.Fa head . +.Pp +The macro .Nm LIST_SWAP swaps the contents of .Fa head1 @@ -1072,6 +1153,10 @@ removing all entries from the former. The macro .Nm TAILQ_EMPTY evaluates to true if there are no items on the tail queue. +The +.Nm TAILQ_EMPTY_ATOMIC +variant has the same behavior, but can be safely used in contexts where it is +possible that a different thread is concurrently updating the queue. .Pp The macro .Nm TAILQ_ENTRY @@ -1224,6 +1309,28 @@ removes the element from the tail queue. .Pp The macro +.Fn TAILQ_REPLACE +replaces the element +.Fa elm +with +.Fa new +in the tail queue. +The element +.Fa new +must not already be on a list. +.Pp +The macro +.Nm TAILQ_SPLIT_AFTER +splits the tail queue referenced by +.Fa head , +making +.Fa rest +reference the tail queue formed by elements after +.Fa elm +in +.Fa head . +.Pp +The macro .Nm TAILQ_SWAP swaps the contents of .Fa head1 @@ -1238,7 +1345,7 @@ struct entry { ... TAILQ_ENTRY(entry) entries; /* Tail queue. */ ... -} *n1, *n2, *n3, *np; +} *n1, *n2, *n3, *n4, *np; TAILQ_INIT(&head); /* Initialize the queue. */ @@ -1256,6 +1363,10 @@ TAILQ_INSERT_BEFORE(n2, n3, entries); TAILQ_REMOVE(&head, n2, entries); /* Deletion. */ free(n2); + +n4 = malloc(sizeof(struct entry)); /* Replacement. */ +TAILQ_REPLACE(&head, n3, n4, entries); +free(n3); /* Forward traversal. */ TAILQ_FOREACH(np, &head, entries) np-> ... @@ -1285,49 +1396,87 @@ while (n1 != NULL) { TAILQ_INIT(&head); .Ed .Sh DIAGNOSTICS -When debugging -.Nm queue(3) , -it can be useful to trace queue changes. -To enable tracing, define the macro -.Va QUEUE_MACRO_DEBUG_TRACE -at compile time. -.Pp -It can also be useful to trash pointers that have been unlinked from a queue, -to detect use after removal. -To enable pointer trashing, define the macro -.Va QUEUE_MACRO_DEBUG_TRASH -at compile time. -The macro -.Fn QMD_IS_TRASHED "void *ptr" -returns true if -.Fa ptr -has been trashed by the -.Va QUEUE_MACRO_DEBUG_TRASH -option. +.Nm queue(3) +provides several diagnostic and debugging facilities. +.Pp +Check code that performs basic integrity and API conformance checks is +automatically inserted when using queue macros in the kernel if compiling it +with +.Va INVARIANTS . +One can request insertion or elision of check code by respectively defining one +of the macros +.Va QUEUE_MACRO_DEBUG_ASSERTIONS +or +.Va QUEUE_MACRO_NO_DEBUG_ASSERTIONS +before first inclusion of +.In sys/queue.h . +When check code encounters an anomaly, it panics the kernel or aborts the +program. +To this end, in the kernel or in +.Va _STANDALONE +builds, it by default calls +.Fn panic , +while in userland builds it prints the diagnostic message on +.Dv stderr +and then calls +.Fn abort . +These behaviors can be overridden by defining a custom +.Fn QMD_PANIC +macro before first inclusion of +.In sys/queue.h . +The diagnostic messages automatically include the source file, line and function +where the failing check occurred. +This behavior can be overridden by defining a custom +.Fn QMD_ASSERT +macro before first inclusion of +.In sys/queue.h . .Pp -In the kernel (with -.Va INVARIANTS -enabled), the +The .Fn SLIST_REMOVE_PREVPTR macro is available to aid debugging: .Bl -hang -offset indent .It Fn SLIST_REMOVE_PREVPTR "TYPE **prev" "TYPE *elm" "SLIST_ENTRY NAME" .Pp -Removes +Removes element .Fa elm , which must directly follow the element whose .Va &SLIST_NEXT() is .Fa prev , -from the SLIST. -This macro validates that +from the list. +This macro may insert, under conditions detailed above, check code that +validates that .Fa elm -follows +indeed follows .Fa prev -in -.Va INVARIANTS -mode. +in the list +.Po +through the +.Fn QMD_SLIST_CHECK_PREVPTR +macro +.Pc . .El +.Pp +When debugging, it can be useful to trace queue changes. +To enable tracing, define the macro +.Va QUEUE_MACRO_DEBUG_TRACE . +Note that, at the moment, only macros for regular tail queues have been +instrumented. +.Pp +It can also be useful to trash pointers that have been unlinked from a queue, +to detect use after removal. +To enable pointer trashing, define the macro +.Va QUEUE_MACRO_DEBUG_TRASH +at compile time. +Note that, at the moment, only a limited number of macros have been +instrumented. +The macro +.Fn QMD_IS_TRASHED "void *ptr" +returns true if +.Fa ptr +has been trashed by the +.Va QUEUE_MACRO_DEBUG_TRASH +option. .Sh SEE ALSO .Xr arb 3 , .Xr tree 3 diff --git a/share/man/man3/sigevent.3 b/share/man/man3/sigevent.3 index fea8e621f3ea..731b365801cc 100644 --- a/share/man/man3/sigevent.3 +++ b/share/man/man3/sigevent.3 @@ -23,8 +23,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd February 25, 2020 .Dt SIGEVENT 3 .Os diff --git a/share/man/man3/siginfo.3 b/share/man/man3/siginfo.3 index 7f8a809cdfa5..59e3ecf8f3e8 100644 --- a/share/man/man3/siginfo.3 +++ b/share/man/man3/siginfo.3 @@ -25,8 +25,6 @@ .\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd February 17, 2021 .Dt SIGINFO 3 .Os @@ -226,7 +224,7 @@ raised by a hardware watchpoint exception may report the data address that triggered the watchpoint in .Va si_addr . .Pp -Sychronous signals set +Synchronous signals set .Va si_trapno to a machine-dependent trap number. .Pp diff --git a/share/man/man3/snl.3 b/share/man/man3/snl.3 new file mode 100644 index 000000000000..04bae46691bf --- /dev/null +++ b/share/man/man3/snl.3 @@ -0,0 +1,309 @@ +.\" +.\" Copyright (C) 2022 Alexander Chernikov <melifaro@FreeBSD.org>. +.\" +.\" 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 December 16, 2022 +.Dt SNL 3 +.Os +.Sh NAME +.Nm snl_init , +.Nm snl_free , +.Nm snl_read_message , +.Nm snl_send , +.Nm snl_get_seq , +.Nm snl_allocz , +.Nm snl_clear_lb , +.Nm snl_parse_nlmsg , +.Nm snl_parse_header , +.Nm snl_parse_attrs , +.Nm snl_parse_attrs_raw , +.Nm snl_attr_get_flag , +.Nm snl_attr_get_ip , +.Nm snl_attr_get_uint16 , +.Nm snl_attr_get_uint32 , +.Nm snl_attr_get_string , +.Nm snl_attr_get_stringn , +.Nm snl_attr_get_nla , +.Nm snl_field_get_uint8 , +.Nm snl_field_get_uint16 , +.Nm snl_field_get_uint32 +.Nd "simple netlink library" +.Sh SYNOPSIS +.In netlink/netlink_snl.h +.In netlink/netlink_snl_route.h +.Ft "bool" +.Fn snl_init "struct snl_state *ss" "int netlink_family" +.Fn snl_free "struct snl_state *ss" +.Ft "struct nlmsghdr *" +.Fn snl_read_message "struct snl_state *ss" +.Ft "bool" +.Fn snl_send "struct snl_state *ss" "void *data" "int sz" +.Ft "uint32_t" +.Fn snl_get_seq "struct snl_state *ss" +.Ft "void *" +.Fn snl_allocz "struct snl_state *ss" "int len" +.Fn snl_clear_lb "struct snl_state *ss" +.Ft "bool" +.Fn snl_parse_nlmsg "struct snl_state *ss" "struct nlmsghdr *hdr" "const struct snl_hdr_parser *ps" "void *target" +.Ft "bool" +.Fn snl_parse_header "struct snl_state *ss" "void *hdr" "int len" "const struct snl_hdr_parser *ps" "int pslen" "void *target" +.Ft "bool" +.Fn snl_parse_attrs "struct snl_state *ss" "struct nlmsghdr *hdr" "int hdrlen" "const struct snl_attr_parser *ps" "int pslen" "void *target" +.Ft "bool" +.Fn snl_parse_attrs_raw "struct snl_state *ss" "struct nlattr *nla_head" "int len" "const struct snl_attr_parser *ps" "int pslen" "void *target" +.Ft "bool" +.Fn snl_attr_get_flag "struct snl_state *ss" "struct nlattr *nla" "void *target" +.Ft "bool" +.Fn snl_attr_get_uint8 "struct snl_state *ss" "struct nlattr *nla" "void *target" +.Ft "bool" +.Fn snl_attr_get_uint16 "struct snl_state *ss" "struct nlattr *nla" "void *target" +.Ft "bool" +.Fn snl_attr_get_uint32 "struct snl_state *ss" "struct nlattr *nla" "void *target" +.Ft "bool" +.Fn snl_attr_get_uint64 "struct snl_state *ss" "struct nlattr *nla" "void *target" +.Ft "bool" +.Fn snl_attr_get_string "struct snl_state *ss" "struct nlattr *nla" "void *target" +.Ft "bool" +.Fn snl_attr_get_stringn "struct snl_state *ss" "struct nlattr *nla" "void *target" +.Ft "bool" +.Fn snl_attr_get_nla "struct snl_state *ss" "struct nlattr *nla" "void *target" +.Ft "bool" +.Fn snl_attr_get_ip "struct snl_state *ss" "struct nlattr *nla" "void *target" +.Ft "bool" +.Fn snl_attr_get_ipvia "struct snl_state *ss" "struct nlattr *nla" "void *target" +.Sh DESCRIPTION +The +.Xr snl 3 +library provides an easy way of sending and receiving Netlink messages, +taking care of serialisation and deserialisation. +.Ss INITIALISATION +Call +.Fn snl_init +with a pointer to the +.Dv struct snl_state +and the desired Netlink family to initialise the library instance. +To free the library instance, call +.Fn snl_free . +.Pp +The library functions are NOT multithread-safe. +If multithreading is desired, consider initializing an instance +per thread. +.Ss MEMORY ALLOCATION +The library uses pre-allocated extendable memory buffers to handle message parsing. +The typical usage pattern is to allocate the necessary data structures during the +message parsing or writing process via +.Fn snl_allocz +and free all allocated data at once using +.Fn snl_clear_lb +after handling the message. +.Ss COMPOSING AND SENDING MESSAGES +The library does not currently offer any wrappers for writing netlink messages. +Simple request messages can be composed by filling in all needed fields directly. +Example for constructing an interface dump request: +.Bd -literal + struct { + struct nlmsghdr hdr; + struct ifinfomsg ifmsg; + } msg = { + .hdr.nlmsg_type = RTM_GETLINK, + .hdr.nlmsg_flags = NLM_F_DUMP | NLM_F_REQUEST, + .hdr.nlmsg_seq = snl_get_seq(ss), + }; + msg.hdr.nlmsg_len = sizeof(msg); +.Ed +.Fn snl_get_seq +can be used to generate a unique message number. +To send the resulting message, +.Fn snl_send +can be used. +.Ss RECEIVING AND PARSING MESSAGES +To receive a message, use +.Fn snl_read_message . +Currently, this call is blocking. +.Pp +The library provides an easy way to convert the message to the pre-defined C +structure. +For each message type, one needs to define rules, converting the protocol header +fields and the desired attributes to the specified structure. +It can be accomplished by using message parsers. +Each message parser consists of an array of attribute getters and an array of +header field getters. +The former array needs to be sorted by the attribute type. +There is a +.Fn SNL_VERIFY_PARSERS +macro to check if the order is correct. +.Fn SNL_DECLARE_PARSER "parser_name" "family header type" "struct snl_field_parser[]" "struct snl_attr_parser[]" +can be used to create a new parser. +.Fn SNL_DECLARE_ATTR_PARSER "parser_name" "struct snl_field_parser[]" +can be used to create an attribute-only message parser. +.Pp +Each attribute getter needs to be embedded in the following structure: +.Bd -literal +typedef bool snl_parse_attr_f(struct snl_state *ss, struct nlattr *attr, const void *arg, void *target); +struct snl_attr_parser { + uint16_t type; /* Attribute type */ + uint16_t off; /* field offset in the target structure */ + snl_parse_attr_f *cb; /* getter function to call */ + const void *arg; /* getter function custom argument */ +}; +.Ed +The generic attribute getter has the following signature: +.Ft "bool" +.Fn snl_attr_get_<type> "struct snl_state *ss" "struct nlattr *nla" "const void *arg" "void *target" . +nla contains the pointer of the attribute to use as the datasource. +The target field is the pointer to the field in the target structure. +It is up to the getter to know the type of the target field. +The getter must check the input attribute and return +false if the attribute is not formed correctly. +Otherwise, the getter fetches the attribute value and stores it in the target, +then returns true. +It is possible to use +.Fn snl_allocz +to create the desired data structure . +A number of predefined getters for the common data types exist. +.Fn snl_attr_get_flag +converts a flag-type attribute to an uint8_t value of 1 or 0, depending on the +attribute presence. +.Fn snl_attr_get_uint8 +stores a uint8_t type attribute into the uint8_t target field. +.Fn snl_attr_get_uint16 +stores a uint16_t type attribute into the uint16_t target field. +.Fn snl_attr_get_uint32 +stores a uint32_t type attribute into the uint32_t target field. +.Fn snl_attr_get_uint64 +stores a uint64_t type attribute into the uint64_t target field. +.Fn snl_attr_get_ip +and +.Fn snl_attr_get_ipvia +stores a pointer to the sockaddr structure with the IPv4/IPv6 address contained +in the attribute. +Sockaddr is allocated using +.Fn snl_allocz . +.Fn snl_attr_get_string +stores a pointer to the NULL-terminated string. +The string itself is allocated using +.Fn snl_allocz . +.Fn snl_attr_get_nla +stores a pointer to the specified attribute. +.Fn snl_attr_get_stringn +stores a pointer to the non-NULL-terminated string. +.Pp +Similarly, each family header getter needs to be embedded in the following structure: +.Bd -literal +typedef void snl_parse_field_f(struct snl_state *ss, void *hdr, void *target); +struct snl_field_parser { + uint16_t off_in; /* field offset in the input structure */ + uint16_t off_out;/* field offset in the target structure */ + snl_parse_field_f *cb; /* getter function to call */ +}; +.Ed +The generic field getter has the following signature: +.Ft "void" +snl_field_get_<type> "struct snl_state *ss" "void *src" "void *target" . +A number of pre-defined getters for the common data types exist. +.Fn "snl_field_get_uint8" +fetches an uint8_t value and stores it in the target. +.Fn "snl_field_get_uint16" +fetches an uint8_t value and stores it in the target. +.Fn "snl_field_get_uint32" +fetches an uint32_t value and stores it in the target. +.Sh EXAMPLES +The following example demonstrates how to list all system interfaces +using netlink. +.Bd -literal +#include <stdio.h> + +#include <netlink/netlink.h> +#include <netlink/netlink_route.h> +#include "netlink/netlink_snl.h" +#include "netlink/netlink_snl_route.h" + +struct nl_parsed_link { + uint32_t ifi_index; + uint32_t ifla_mtu; + char *ifla_ifname; +}; + +#define _IN(_field) offsetof(struct ifinfomsg, _field) +#define _OUT(_field) offsetof(struct nl_parsed_link, _field) +static const struct snl_attr_parser ap_link[] = { + { .type = IFLA_IFNAME, .off = _OUT(ifla_ifname), .cb = snl_attr_get_string }, + { .type = IFLA_MTU, .off = _OUT(ifla_mtu), .cb = snl_attr_get_uint32 }, +}; +static const struct snl_field_parser fp_link[] = { + {.off_in = _IN(ifi_index), .off_out = _OUT(ifi_index), .cb = snl_field_get_uint32 }, +}; +#undef _IN +#undef _OUT +SNL_DECLARE_PARSER(link_parser, struct ifinfomsg, fp_link, ap_link); + + +int +main(int ac, char *argv[]) +{ + struct snl_state ss; + + if (!snl_init(&ss, NETLINK_ROUTE)) + return (1); + + struct { + struct nlmsghdr hdr; + struct ifinfomsg ifmsg; + } msg = { + .hdr.nlmsg_type = RTM_GETLINK, + .hdr.nlmsg_flags = NLM_F_DUMP | NLM_F_REQUEST, + .hdr.nlmsg_seq = snl_get_seq(&ss), + }; + msg.hdr.nlmsg_len = sizeof(msg); + + if (!snl_send(&ss, &msg, sizeof(msg))) { + snl_free(&ss); + return (1); + } + + struct nlmsghdr *hdr; + while ((hdr = snl_read_message(&ss)) != NULL && hdr->nlmsg_type != NLMSG_DONE) { + if (hdr->nlmsg_seq != msg.hdr.nlmsg_seq) + break; + + struct nl_parsed_link link = {}; + if (!snl_parse_nlmsg(&ss, hdr, &link_parser, &link)) + continue; + printf("Link#%u %s mtu %u\en", link.ifi_index, link.ifla_ifname, link.ifla_mtu); + } + + return (0); +} +.Ed +.Sh SEE ALSO +.Xr genetlink 4 , +.Xr netlink 4 , +and +.Xr rtnetlink 4 +.Sh HISTORY +The +.Dv SNL +library appeared in +.Fx 13.2 . +.Sh AUTHORS +This library was implemented by +.An Alexander Chernikov Aq Mt melifaro@FreeBSD.org . diff --git a/share/man/man3/stats.3 b/share/man/man3/stats.3 index 2a63febef1d6..7fe1fa613def 100644 --- a/share/man/man3/stats.3 +++ b/share/man/man3/stats.3 @@ -23,8 +23,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd December 2, 2019 .Dt STATS 3 .Os @@ -104,17 +102,17 @@ .Fc .Ft struct voistatspec .Fo "STATS_VSS_CRHIST<32|64>_USR" -.Fa Sy "HBKTS" Ns Pq Sy "CRBKT" Ns ( Em "lb" ) , "..." Pc , +.Fa Sy "HBKTS" Ns Pq Sy "CRBKT" Ns ( Em "lb" ) , "..." , .Fa "vsdflags" .Fc .Ft struct voistatspec .Fo "STATS_VSS_DRHIST<32|64>_USR" -.Fa Sy "HBKTS" Ns Pq Sy "DRBKT" Ns ( Em "lb" , "ub" ) , "..." Pc , +.Fa Sy "HBKTS" Ns Pq Sy "DRBKT" Ns ( Em "lb" , "ub" ) , "..." , .Fa "vsdflags" .Fc .Ft struct voistatspec .Fo "STATS_VSS_DVHIST<32|64>_USR" -.Fa Sy "HBKTS" Ns Pq Sy "DVBKT" Ns ( Em "val" ) , "..." Pc , +.Fa Sy "HBKTS" Ns Pq Sy "DVBKT" Ns ( Em "val" ) , "..." , .Fa "vsdflags" .Fc .Ft struct voistatspec @@ -318,16 +316,16 @@ The maximum VOI value. The minimum VOI value. .It Dv VS_STYPE_HIST A static bucket histogram of VOI values, including a count of -.Dq out-of-band/bucket Dc +.Dq out-of-band/bucket values which did not match any bucket. Histograms can be specified as -.Dq Em C Ns ontinuous Em R Ns ange Dc -.Pq CRHIST Pc , -.Dq Em D Ns iscrete Em R Ns ange Dc -.Pq DRHIST Pc +.Dq Em C Ns ontinuous Em R Ns ange +.Pq CRHIST , +.Dq Em D Ns iscrete Em R Ns ange +.Pq DRHIST or -.Dq Em D Ns iscrete Em V Ns alue Dc -.Pq DVHIST Pc , +.Dq Em D Ns iscrete Em V Ns alue +.Pq DVHIST , with 32 or 64 bit bucket counters, depending on the VOI semantics. .It Dv VS_STYPE_TDGST A dynamic bucket histogram of VOI values based on the t-digest method @@ -435,15 +433,15 @@ Where templates need to be referenced via textual means, for example via a MIB variable, the following string based template spec formats can be used: .Bl -enum .It -.Qq <tplname> Qc Ns +.Qq <tplname> Ns :<tplhash> .Ns , for example -.Qq TCP_DEFAULT Qc Ns +.Qq TCP_DEFAULT Ns :1731235399 .It -.Qq <tplname> Qc +.Qq <tplname> .Ns , for example -.Qq TCP_DEFAULT Qc +.Qq TCP_DEFAULT .It :<tplhash> .Ns , for example diff --git a/share/man/man3/stdarg.3 b/share/man/man3/stdarg.3 index 3b47eee70ff0..71409508e6a8 100644 --- a/share/man/man3/stdarg.3 +++ b/share/man/man3/stdarg.3 @@ -29,10 +29,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" @(#)stdarg.3 8.1 (Berkeley) 6/5/93 -.\" $FreeBSD$ -.\" -.Dd February 25, 2020 +.Dd October 18, 2024 .Dt STDARG 3 .Os .Sh NAME @@ -205,9 +202,6 @@ void foo(char *fmt, ...) These macros are .Em not compatible with the historic macros they replace. -A backward compatible version can be found in the include -file -.In varargs.h . .Sh STANDARDS The .Fn va_start , diff --git a/share/man/man3/stdckdint.3 b/share/man/man3/stdckdint.3 new file mode 100644 index 000000000000..e3593472c08b --- /dev/null +++ b/share/man/man3/stdckdint.3 @@ -0,0 +1,106 @@ +.\"- +.\" Copyright (c) 2023 Dag-Erling Smørgrav +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd September 5, 2023 +.Dt STDCKDINT 3 +.Os +.Sh NAME +.Nm stdckdint +.Nd checked integer arithmetic +.Sh SYNOPSIS +.In stdckdint.h +.Ft bool +.Fn ckd_add "type1 *result" "type2 a" "type3 b" +.Ft bool +.Fn ckd_sub "type1 *result" "type2 a" "type3 b" +.Ft bool +.Fn ckd_mul "type1 *result" "type2 a" "type3 b" +.Sh DESCRIPTION +The function-like macros +.Nm ckd_add , +.Nm ckd_sub , +and +.Nm ckd_mul +perform checked integer addition, subtraction, and multiplication, +respectively. +If the result of adding, subtracting, or multiplying +.Fa a +and +.Fa b +as if their respective types had infinite range fits in +.Ft type1 , +it is stored in the location pointed to by +.Fa result +and the macro evaluates to +.Dv false . +Otherwise, the macro evaluates to +.Dv true +and the contents of the location pointed to by +.Fa result +is the result of the operation wrapped to the range of +.Ft type1 . +.Sh RETURN VALUES +The +.Nm ckd_add , +.Nm ckd_sub , +and +.Nm ckd_mul +macros evaluate to +.Dv true +if the requested operation overflowed the result type and +.Dv false +otherwise. +.Sh EXAMPLES +.Bd -literal -offset indent +#include <assert.h> +#include <limits.h> +#include <stdckdint.h> + +int main(void) +{ + int result; + + assert(!ckd_add(&result, INT_MAX, 0)); + assert(result == INT_MAX); + assert(ckd_add(&result, INT_MAX, 1)); + assert(result == INT_MIN); + + assert(!ckd_sub(&result, INT_MIN, 0)); + assert(result == INT_MIN); + assert(ckd_sub(&result, INT_MIN, 1)); + assert(result == INT_MAX); + + assert(!ckd_mul(&result, INT_MAX / 2, 2)); + assert(result == INT_MAX - 1); + assert(ckd_mul(&result, INT_MAX / 2 + 1, 2)); + assert(result == INT_MIN); + + return 0; +} +.Ed +.\" .Sh STANDARDS +.\" The +.\" .Nm ckd_add , +.\" .Nm ckd_sub , +.\" and +.\" .Nm ckd_mul +.\" macros conform to +.\" .St -isoC-23 . +.Sh HISTORY +The +.Nm ckd_add , +.Nm ckd_sub , +and +.Nm ckd_mul +macros were first introduced in +.Fx 14.0 . +.Sh AUTHORS +The +.Nm ckd_add , +.Nm ckd_sub , +and +.Nm ckd_mul +macros and this manual page were written by +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . diff --git a/share/man/man3/sysexits.3 b/share/man/man3/sysexits.3 index a0f9af98d42e..62f79b286a16 100644 --- a/share/man/man3/sysexits.3 +++ b/share/man/man3/sysexits.3 @@ -1,7 +1,7 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause .\" -.\" Copyright (c) 1996 Joerg Wunsch -.\" -.\" All rights reserved. +.\" Copyright (c) 1996 Joerg Wunsch. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -23,29 +23,20 @@ .\" (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 January 21, 2010 +.Dd May 9, 2024 .Dt SYSEXITS 3 .Os .Sh NAME .Nm sysexits -.Nd preferable exit codes for programs +.Nd legacy exit status codes for system programs .Sh SYNOPSIS .In sysexits.h .Sh DESCRIPTION -According to -.Xr style 9 , -it is not a good practice to call -.Xr exit 3 -with arbitrary values to indicate a failure condition when ending -a program. -Instead, the pre-defined exit codes from -.Nm -should be used, so the caller of the process can get a rough -estimation about the failure class without looking up the source code. -.Pp +Some commands attempt to describe the nature of a failure condition +by using these pre-defined exit codes. +This interface has been deprecated and is retained only for compatibility. +Its use is discouraged. +.Sh ERRORS The successful exit is always indicated by a status of 0, or .Sy EX_OK . Error numbers begin at @@ -114,8 +105,7 @@ The remote system returned something that was during a protocol exchange. .It Sy EX_NOPERM Pq 77 You did not have sufficient permission to perform the operation. -This -is not intended for file system problems, which should use +This is not intended for file system problems, which should use .Sy EX_NOINPUT or .Sy EX_CANTCREAT , @@ -133,12 +123,13 @@ parenthesis for easy reference. .Sh HISTORY The .Nm -file appeared somewhere after -.Bx 4.3 . +file first appeared in +.Bx 4 . .Sh AUTHORS This manual page was written by -.An J\(:org Wunsch -after the comments in -.In sysexits.h . +.An J\(:org Wunsch . .Sh BUGS -The choice of an appropriate exit value is often ambiguous. +.Bl -tag -width 0 -compact +.It This interface is not portable. +.It The choice of an appropriate exit value is often ambiguous. +.El diff --git a/share/man/man3/tgmath.3 b/share/man/man3/tgmath.3 index be49dfa87b18..98dbb7439793 100644 --- a/share/man/man3/tgmath.3 +++ b/share/man/man3/tgmath.3 @@ -22,8 +22,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd January 4, 2012 .Dt TGMATH 3 .Os diff --git a/share/man/man3/timeradd.3 b/share/man/man3/timeradd.3 index 055bef9668f2..9720267883ef 100644 --- a/share/man/man3/timeradd.3 +++ b/share/man/man3/timeradd.3 @@ -25,8 +25,6 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $FreeBSD$ -.\" .Dd July 30, 2018 .Dt TIMERADD 3 .Os @@ -87,6 +85,7 @@ struct timeval { long tv_usec; /* and microseconds */ }; .Ed +.Pp And the .Fa timespec structure is defined in diff --git a/share/man/man3/tree.3 b/share/man/man3/tree.3 index 7e3727b2c365..83d005a5e481 100644 --- a/share/man/man3/tree.3 +++ b/share/man/man3/tree.3 @@ -28,9 +28,7 @@ .\" (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 July 27, 2020 +.Dd August 2, 2024 .Dt TREE 3 .Os .Sh NAME @@ -97,9 +95,12 @@ .Nm RB_FOREACH_REVERSE_SAFE , .Nm RB_INIT , .Nm RB_INSERT , +.Nm RB_INSERT_NEXT , +.Nm RB_INSERT_PREV , .Nm RB_REMOVE , .Nm RB_REINSERT , .Nm RB_AUGMENT +.Nm RB_AUGMENT_CHECK, .Nm RB_UPDATE_AUGMENT .Nd "implementations of splay and rank-balanced (wavl) trees" .Sh SYNOPSIS @@ -192,11 +193,17 @@ .Ft "struct TYPE *" .Fn RB_INSERT NAME "RB_HEAD *head" "struct TYPE *elm" .Ft "struct TYPE *" +.Fn RB_INSERT_NEXT NAME "RB_HEAD *head" "struct TYPE *elm" "struct TYPE *next" +.Ft "struct TYPE *" +.Fn RB_INSERT_PREV NAME "RB_HEAD *head" "struct TYPE *elm" "struct TYPE *prev" +.Ft "struct TYPE *" .Fn RB_REMOVE NAME "RB_HEAD *head" "struct TYPE *elm" .Ft "struct TYPE *" .Fn RB_REINSERT NAME "RB_HEAD *head" "struct TYPE *elm" .Ft "void" .Fn RB_AUGMENT NAME "struct TYPE *elm" +.Ft "bool" +.Fn RB_AUGMENT_CHECK NAME "struct TYPE *elm" .Ft "void" .Fn RB_UPDATE_AUGMENT NAME "struct TYPE *elm" .Sh DESCRIPTION @@ -512,6 +519,18 @@ macro inserts the new element into the tree. .Pp The +.Fn RB_INSERT_NEXT +macro inserts the new element +.Fa elm +into the tree immediately after a given element. +.Pp +The +.Fn RB_INSERT_PREV +macro inserts the new element +.Fa elm +into the tree immediately before a given element. +.Pp +The .Fn RB_REMOVE macro removes the element .Fa elm @@ -620,6 +639,22 @@ It is typically used to maintain some associative accumulation of tree elements, such as sums, minima, maxima, and the like. .Pp The +.Fn RB_AUGMENT_CHECK +macro updates augmentation data of the element +.Fa elm +in the tree. +By default, it does nothing and returns false. +If +.Fn RB_AUGMENT_CHECK +is defined, then when an element is inserted or removed from the tree, +it is invoked for every element in the tree that is the root of an +altered subtree, working from the bottom of the tree up toward the +top, until it returns false to indicate that it did not change the +element and so working further up the tree would change nothing. +It is typically used to maintain some associative accumulation of tree +elements, such as sums, minima, maxima, and the like. +.Pp +The .Fn RB_UPDATE_AUGMENT macro updates augmentation data of the element .Fa elm @@ -640,6 +675,8 @@ To maintain the sum of the values in the tree, each element maintains the sum of its value and the sums from its left and right subtrees. Lastly, the internal structure of the tree is printed. .Bd -literal -offset 3n +#define RB_AUGMENT(entry) sumaug(entry) + #include <sys/tree.h> #include <err.h> #include <stdio.h> @@ -656,7 +693,7 @@ intcmp(struct node *e1, struct node *e2) return (e1->i < e2->i ? -1 : e1->i > e2->i); } -int +void sumaug(struct node *e) { e->sum = e->i; @@ -665,7 +702,6 @@ sumaug(struct node *e) if (RB_RIGHT(e, entry) != NULL) e->sum += RB_RIGHT(e, entry)->sum; } -#define RB_AUGMENT(entry) sumaug(entry) RB_HEAD(inttree, node) head = RB_INITIALIZER(&head); RB_GENERATE(inttree, node, entry, intcmp) @@ -714,8 +750,7 @@ main(void) printf("%d\en", n->i); } print_tree(RB_ROOT(&head)); - printf("Sum of values = %d\n", RB_ROOT(&head)->sum); - printf("\en"); + printf("\enSum of values = %d\en", RB_ROOT(&head)->sum); return (0); } .Ed |