diff options
Diffstat (limited to 'share/man/man3')
102 files changed, 889 insertions, 320 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..5c8dced71743 100644 --- a/share/man/man3/Makefile +++ b/share/man/man3/Makefile @@ -1,5 +1,3 @@ -# @(#)Makefile 8.2 (Berkeley) 12/13/93 -# $FreeBSD$ .include <src.opts.mk> @@ -27,8 +25,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 +215,7 @@ 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_SWAP.3 \ queue.3 SLIST_CLASS_ENTRY.3 \ queue.3 SLIST_CLASS_HEAD.3 \ @@ -283,6 +284,7 @@ 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_SWAP.3 MLINKS+= stats.3 stats_tpl_alloc.3 \ stats.3 stats_tpl_fetch_allocid.3 \ @@ -310,6 +312,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 +325,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,6 +452,7 @@ PTHREAD_MAN= pthread.3 \ pthread_set_name_np.3 \ pthread_setspecific.3 \ pthread_sigmask.3 \ + pthread_sigqueue.3 \ pthread_spin_init.3 \ pthread_spin_lock.3 \ pthread_suspend_all_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/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..bfc0eb5ca139 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 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..39897eb565cd 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 16, 2023 .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. @@ -272,13 +275,105 @@ 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..f3b1d3639827 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 @@ -114,6 +112,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 +157,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..ac44a8d99718 100644 --- a/share/man/man3/pthread_mutex_consistent.3 +++ b/share/man/man3/pthread_mutex_consistent.3 @@ -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..8f4d0d9a06a4 100644 --- a/share/man/man3/pthread_mutexattr.3 +++ b/share/man/man3/pthread_mutexattr.3 @@ -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_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..2f9fe7099ef2 100644 --- a/share/man/man3/pthread_rwlockattr_destroy.3 +++ b/share/man/man3/pthread_rwlockattr_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_RWLOCKATTR_DESTROY 3 .Os 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..46100608f9b6 100644 --- a/share/man/man3/pthread_rwlockattr_init.3 +++ b/share/man/man3/pthread_rwlockattr_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 4, 1998 .Dt PTHREAD_RWLOCKATTR_INIT 3 .Os 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_sigqueue.3 b/share/man/man3/pthread_sigqueue.3 new file mode 100644 index 000000000000..bf5dd62f04e6 --- /dev/null +++ b/share/man/man3/pthread_sigqueue.3 @@ -0,0 +1,102 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright 2024 The FreeBSD Foundation, Inc. +.\" +.\" 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 index ddfa630ffd9a..f02ff15eedc3 100644 --- a/share/man/man3/pthread_switch_add_np.3 +++ b/share/man/man3/pthread_switch_add_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_SWITCH_ADD_NP 3 .Os diff --git a/share/man/man3/pthread_testcancel.3 b/share/man/man3/pthread_testcancel.3 index 9ba1403dffdc..2d2bb06c48e2 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 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..be890fd2cc88 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 8, 2024 .Dt QUEUE 3 .Os .Sh NAME @@ -93,6 +90,7 @@ .Nm LIST_NEXT , .Nm LIST_PREV , .Nm LIST_REMOVE , +.Nm LIST_REPLACE , .Nm LIST_SWAP , .Nm TAILQ_CLASS_ENTRY , .Nm TAILQ_CLASS_HEAD , @@ -119,6 +117,7 @@ .Nm TAILQ_NEXT , .Nm TAILQ_PREV , .Nm TAILQ_REMOVE , +.Nm TAILQ_REPLACE , .Nm TAILQ_SWAP .Nd implementations of singly-linked lists, singly-linked tail queues, lists and tail queues @@ -188,6 +187,7 @@ 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_SWAP "LIST_HEAD *head1" "LIST_HEAD *head2" "TYPE" "LIST_ENTRY NAME" .\" .Fn TAILQ_CLASS_ENTRY "CLASSTYPE" @@ -215,6 +215,7 @@ 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_SWAP "TAILQ_HEAD *head1" "TAILQ_HEAD *head2" "TYPE" "TAILQ_ENTRY NAME" .\" .Sh DESCRIPTION @@ -966,6 +967,17 @@ 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_SWAP swaps the contents of .Fa head1 @@ -1224,6 +1236,17 @@ 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_SWAP swaps the contents of .Fa head1 @@ -1238,7 +1261,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 +1279,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-> ... 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..f57cf5f7d706 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 diff --git a/share/man/man3/snl.3 b/share/man/man3/snl.3 new file mode 100644 index 000000000000..9a6eceb66a32 --- /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\n", 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..4dfb1dac63a2 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 diff --git a/share/man/man3/stdarg.3 b/share/man/man3/stdarg.3 index 3b47eee70ff0..b7346c91d7a3 100644 --- a/share/man/man3/stdarg.3 +++ b/share/man/man3/stdarg.3 @@ -29,9 +29,6 @@ .\" 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 .Dt STDARG 3 .Os 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..6ce601f25150 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 diff --git a/share/man/man3/tree.3 b/share/man/man3/tree.3 index c68c71fff85b..e6d855c5ade0 100644 --- a/share/man/man3/tree.3 +++ b/share/man/man3/tree.3 @@ -28,8 +28,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 July 27, 2020 .Dt TREE 3 .Os @@ -97,9 +95,13 @@ .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 .In sys/tree.h @@ -191,11 +193,19 @@ .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 These macros define data structures for different types of trees: splay trees and rank-balanced (wavl) trees. @@ -509,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 @@ -520,10 +542,25 @@ The and .Fn RB_NFIND macros can be used to find a particular element in the tree. +.Pp +The +.Fn RB_FIND +macro returns the element in the tree equal to the provided +key, or +.Dv NULL +if there is no such element. +.Pp +The +.Fn RB_NFIND +macro returns the least element greater than or equal to the provided +key, or +.Dv NULL +if there is no such element. .Bd -literal -offset indent -struct TYPE find, *res; +struct TYPE find, *res, *resn; find.key = 30; res = RB_FIND(NAME, head, &find); +resn = RB_NFIND(NAME, head, &find); .Ed .Pp The @@ -592,12 +629,43 @@ macro updates augmentation data of the element in the tree. By default, it has no effect. It is not meant to be invoked by the RB user. -If RB_AUGMENT is defined by the RB user, 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 to the top. +If +.Fn RB_AUGMENT +is defined by the RB user, 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 to +the top. 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 +and its ancestors in the tree. +If +.Fn RB_AUGMENT +is defined by the RB user, then when an element in the +tree is changed, without changing the order of items in the tree, +invoking this function on that element restores consistency of the +augmentation state of the tree as if the element had been removed and +inserted again. .Sh EXAMPLES The following example demonstrates how to declare a rank-balanced tree holding integers. |