diff options
| author | Jacob McDonnell <jacob@jacobmcdonnell.com> | 2026-04-25 16:08:12 -0400 |
|---|---|---|
| committer | Jacob McDonnell <jacob@jacobmcdonnell.com> | 2026-04-25 16:08:12 -0400 |
| commit | b9cde963555b6519c5dbd34a39dee3418f593437 (patch) | |
| tree | 453accad3c3286e3416d4160de4a87223aff684c /static/freebsd/man3 | |
| parent | 5cb84ec742fd33f78c8022863fadaa8d0d93e176 (diff) | |
feat: Added FreeBSD man pages
Diffstat (limited to 'static/freebsd/man3')
104 files changed, 17122 insertions, 0 deletions
diff --git a/static/freebsd/man3/ATOMIC_VAR_INIT.3 b/static/freebsd/man3/ATOMIC_VAR_INIT.3 new file mode 100644 index 00000000..b3dd2423 --- /dev/null +++ b/static/freebsd/man3/ATOMIC_VAR_INIT.3 @@ -0,0 +1,299 @@ +.\" Copyright (c) 2011 Ed Schouten <ed@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd December 27, 2011 +.Dt ATOMIC_VAR_INIT 3 +.Os +.Sh NAME +.Nm ATOMIC_VAR_INIT , +.Nm atomic_init , +.Nm atomic_load , +.Nm atomic_store , +.Nm atomic_exchange , +.Nm atomic_compare_exchange_strong , +.Nm atomic_compare_exchange_weak , +.Nm atomic_fetch_add , +.Nm atomic_fetch_and , +.Nm atomic_fetch_or , +.Nm atomic_fetch_sub , +.Nm atomic_fetch_xor , +.Nm atomic_is_lock_free +.Nd type-generic atomic operations +.Sh SYNOPSIS +.In stdatomic.h +.Pp +_Atomic(T) +.Fa v += ATOMIC_VAR_INIT(c); +.Ft void +.Fn atomic_init "_Atomic(T) *object" "T value" +.Ft T +.Fn atomic_load "_Atomic(T) *object" +.Ft T +.Fn atomic_load_explicit "_Atomic(T) *object" "memory_order order" +.Ft void +.Fn atomic_store "_Atomic(T) *object" "T desired" +.Ft void +.Fn atomic_store_explicit "_Atomic(T) *object" "T desired" "memory_order order" +.Ft T +.Fn atomic_exchange "_Atomic(T) *object" "T desired" +.Ft T +.Fn atomic_exchange_explicit "_Atomic(T) *object" "T desired" "memory_order order" +.Ft _Bool +.Fn atomic_compare_exchange_strong "_Atomic(T) *object" "T *expected" "T desired" +.Ft _Bool +.Fn atomic_compare_exchange_strong_explicit "_Atomic(T) *object" "T *expected" "T desired" "memory_order success" "memory_order failure" +.Ft _Bool +.Fn atomic_compare_exchange_weak "_Atomic(T) *object" "T *expected" "T desired" +.Ft _Bool +.Fn atomic_compare_exchange_weak_explicit "_Atomic(T) *object" "T *expected" "T desired" "memory_order success" "memory_order failure" +.Ft T +.Fn atomic_fetch_add "_Atomic(T) *object" "T operand" +.Ft T +.Fn atomic_fetch_add_explicit "_Atomic(T) *object" "T operand" "memory_order order" +.Ft T +.Fn atomic_fetch_and "_Atomic(T) *object" "T operand" +.Ft T +.Fn atomic_fetch_and_explicit "_Atomic(T) *object" "T operand" "memory_order order" +.Ft T +.Fn atomic_fetch_or "_Atomic(T) *object" "T operand" +.Ft T +.Fn atomic_fetch_or_explicit "_Atomic(T) *object" "T operand" "memory_order order" +.Ft T +.Fn atomic_fetch_sub "_Atomic(T) *object" "T operand" +.Ft T +.Fn atomic_fetch_sub_explicit "_Atomic(T) *object" "T operand" "memory_order order" +.Ft T +.Fn atomic_fetch_xor "_Atomic(T) *object" "T operand" +.Ft T +.Fn atomic_fetch_xor_explicit "_Atomic(T) *object" "T operand" "memory_order order" +.Ft _Bool +.Fn atomic_is_lock_free "const _Atomic(T) *object" +.Sh DESCRIPTION +The header +.In stdatomic.h +provides type-generic macros for atomic operations. +Atomic operations can be used by multithreaded programs to provide +shared variables between threads that in most cases may be modified +without acquiring locks. +.Pp +Atomic variables are declared using the +.Fn _Atomic +type specifier. +These variables are not type-compatible with their non-atomic +counterparts. +Depending on the compiler used, atomic variables may be opaque and can +therefore only be influenced using the macros described. +.Pp +The +.Fn atomic_init +macro initializes the atomic variable +.Fa object +with a +.Fa value . +Atomic variables can be initialized while being declared using +.Fn ATOMIC_VAR_INIT . +.Pp +The +.Fn atomic_load +macro returns the value of atomic variable +.Fa object . +The +.Fn atomic_store +macro sets the atomic variable +.Fa object +to its +.Fa desired +value. +.Pp +The +.Fn atomic_exchange +macro combines the behaviour of +.Fn atomic_load +and +.Fn atomic_store . +It sets the atomic variable +.Fa object +to its desired +.Fa value +and returns the original contents of the atomic variable. +.Pp +The +.Fn atomic_compare_exchange_strong +macro stores a +.Fa desired +value into atomic variable +.Fa object , +only if the atomic variable is equal to its +.Fa expected +value. +Upon success, the macro returns +.Dv true . +Upon failure, the +.Fa desired +value is overwritten with the value of the atomic variable and +.Dv false +is returned. +The +.Fn atomic_compare_exchange_weak +macro is identical to +.Fn atomic_compare_exchange_strong , +but is allowed to fail even if atomic variable +.Fa object +is equal to its +.Fa expected +value. +.Pp +The +.Fn atomic_fetch_add +macro adds the value +.Fa operand +to atomic variable +.Fa object +and returns the original contents of the atomic variable. +.Pp +The +.Fn atomic_fetch_and +macro applies the +.Em and +operator to atomic variable +.Fa object +and +.Fa operand +and stores the value into +.Fa object , +while returning the original contents of the atomic variable. +.Pp +The +.Fn atomic_fetch_or +macro applies the +.Em or +operator to atomic variable +.Fa object +and +.Fa operand +and stores the value into +.Fa object , +while returning the original contents of the atomic variable. +.Pp +The +.Fn atomic_fetch_sub +macro subtracts the value +.Fa operand +from atomic variable +.Fa object +and returns the original contents of the atomic variable. +.Pp +The +.Fn atomic_fetch_xor +macro applies the +.Em xor +operator to atomic variable +.Fa object +and +.Fa operand +and stores the value into +.Fa object , +while returning the original contents of the atomic variable. +.Pp +The +.Fn atomic_is_lock_free +macro returns whether atomic variable +.Fa object +uses locks when using atomic operations. +.Sh BARRIERS +The atomic operations described previously are implemented in such a way +that they disallow both the compiler and the executing processor to +re-order any nearby memory operations across the atomic operation. +In certain cases this behaviour may cause suboptimal performance. +To mitigate this, every atomic operation has an +.Fn _explicit +version that allows the re-ordering to be configured. +.Pp +The +.Fa order +parameter of these +.Fn _explicit +macros can have one of the following values. +.Bl -tag -width memory_order_relaxed +.It Dv memory_order_relaxed +No operation orders memory. +.It Dv memory_order_consume +Perform consume operation. +.It Dv memory_order_acquire +Acquire fence. +.It Dv memory_order_release +Release fence. +.It Dv memory_order_acq_rel +Acquire and release fence. +.It Dv memory_order_seq_cst +Sequentially consistent acquire and release fence. +.El +.Pp +The previously described macros are identical to the +.Fn _explicit +macros, when +.Fa order +is +.Dv memory_order_seq_cst . +.Sh COMPILER SUPPORT +These atomic operations are typically implemented by the compiler, as +they must be implemented type-generically and must often use special +hardware instructions. +As this interface has not been adopted by most compilers yet, the +.In stdatomic.h +header implements these macros on top of existing compiler intrinsics to +provide forward compatibility. +.Pp +This means that certain aspects of the interface, such as support for +different barrier types may simply be ignored. +When using GCC, all atomic operations are executed as if they are using +.Dv memory_order_seq_cst . +.Pp +Instead of using the atomic operations provided by this interface, +.St -isoC-2011 +allows the atomic variables to be modified directly using built-in +language operators. +This behaviour cannot be emulated for older compilers. +To prevent unintended non-atomic access to these variables, this header +file places the atomic variable in a structure when using an older +compiler. +.Pp +When using GCC on architectures on which it lacks support for built-in +atomic intrinsics, these macros may emit function calls to fallback +routines. +These fallback routines are only implemented for 32-bits and 64-bits +datatypes, if supported by the CPU. +.Sh SEE ALSO +.Xr pthread 3 , +.Xr atomic 9 +.Sh STANDARDS +These macros attempt to conform to +.St -isoC-2011 . +.Sh HISTORY +These macros appeared in +.Fx 10.0 . +.Sh AUTHORS +.An \&Ed Schouten Aq Mt ed@FreeBSD.org +.An David Chisnall Aq Mt theraven@FreeBSD.org diff --git a/static/freebsd/man3/CMSG_DATA.3 b/static/freebsd/man3/CMSG_DATA.3 new file mode 100644 index 00000000..27e15613 --- /dev/null +++ b/static/freebsd/man3/CMSG_DATA.3 @@ -0,0 +1,212 @@ +.\" Written by Jared Yanovich <jaredy@openbsd.org> +.\" Public domain, July 3, 2005 +.Dd March 13, 2020 +.Dt CMSG_DATA 3 +.Os +.Sh NAME +.Nm CMSG_DATA , +.Nm CMSG_FIRSTHDR , +.Nm CMSG_LEN , +.Nm CMSG_NXTHDR , +.Nm CMSG_SPACE +.Nd socket control message routines for ancillary data access +.Sh SYNOPSIS +.In sys/socket.h +.Ft unsigned char * +.Fn CMSG_DATA "struct cmsghdr *" +.Ft struct cmsghdr * +.Fn CMSG_FIRSTHDR "struct msghdr *" +.Ft size_t +.Fn CMSG_LEN "size_t" +.Ft struct cmsghdr * +.Fn CMSG_NXTHDR "struct msghdr *" "struct cmsghdr *" +.Ft size_t +.Fn CMSG_SPACE "size_t" +.Sh DESCRIPTION +The control message API is used to construct ancillary data objects for +use in control messages sent and received across sockets. +.Pp +Control messages are passed around by the +.Xr recvmsg 2 +and +.Xr sendmsg 2 +system calls. +The +.Vt cmsghdr +structure, described in +.Xr recvmsg 2 , +is used to specify a chain of control messages. +.Pp +These routines should be used instead of directly accessing the control +message header members and data buffers as they ensure that necessary +alignment constraints are met. +.Pp +The following routines are provided: +.Bl -tag -width Ds +.It Fn CMSG_DATA cmsg +This routine accesses the data portion of the control message header +.Fa cmsg . +It ensures proper alignment constraints on the beginning of ancillary +data are met. +.It Fn CMSG_FIRSTHDR msghdr +This routine accesses the first control message attached to the +message +.Fa msghdr . +If no control messages are attached to the message, this routine +returns +.Dv NULL . +.It Fn CMSG_LEN len +This routine determines the size in bytes of a control message, +which includes the control message header. +.Fa len +specifies the length of the data held by the control message. +This value is what is normally stored in the +.Fa cmsg_len +of each control message. +This routine accounts for any alignment constraints on the beginning of +ancillary data. +.It Fn CMSG_NXTHDR msghdr cmsg +This routine returns the location of the control message following +.Fa cmsg +in the message +.Fa msghdr . +If +.Fa cmsg +is the last control message in the chain, this routine returns +.Dv NULL . +.It Fn CMSG_SPACE len +This routine determines the size in bytes needed to hold a control +message and its contents of length +.Fa len , +which includes the control message header. +This value is what is normally stored in +.Fa msg_msgcontrollen . +This routine accounts for any alignment constraints on the beginning of +ancillary data as well as any needed to pad the next control message. +.El +.Sh EXAMPLES +The following example constructs a control message containing a file descriptor +in the parent process and passes it over a pre-shared socket over the child +process. +Then the child process sends a "hello" string to the parent process using the +received file descriptor. +.Bd -literal +#include <sys/socket.h> + +#include <err.h> +#include <stdio.h> +#include <string.h> +#include <sysexits.h> +#include <unistd.h> + +#define HELLOLEN sizeof("hello") + +int +main() +{ + struct msghdr msg; + union { + struct cmsghdr hdr; + unsigned char buf[CMSG_SPACE(sizeof(int))]; + } cmsgbuf; + char buf[HELLOLEN]; + int hellofd[2]; + int presharedfd[2]; + struct cmsghdr *cmsg; + + if (socketpair(PF_LOCAL, SOCK_STREAM, 0, presharedfd) == -1) + err(EX_OSERR, "failed to create a pre-shared socket pair"); + + memset(&msg, 0, sizeof(msg)); + msg.msg_control = &cmsgbuf.buf; + msg.msg_controllen = sizeof(cmsgbuf.buf); + msg.msg_iov = NULL; + msg.msg_iovlen = 0; + + switch (fork()) { + case -1: + err(EX_OSERR, "fork"); + case 0: + close(presharedfd[0]); + strlcpy(buf, "hello", HELLOLEN); + + if (recvmsg(presharedfd[1], &msg, 0) == -1) + err(EX_IOERR, "failed to receive a message"); + if (msg.msg_flags & (MSG_CTRUNC | MSG_TRUNC)) + errx(EX_IOERR, "control message truncated"); + for (cmsg = CMSG_FIRSTHDR(&msg); cmsg != NULL; + cmsg = CMSG_NXTHDR(&msg, cmsg)) { + if (cmsg->cmsg_len == CMSG_LEN(sizeof(int)) && + cmsg->cmsg_level == SOL_SOCKET && + cmsg->cmsg_type == SCM_RIGHTS) { + hellofd[1] = *(int *)CMSG_DATA(cmsg); + printf("child: sending '%s'\\n", buf); + if (write(hellofd[1], buf, HELLOLEN) == -1) + err(EX_IOERR, "failed to send 'hello'"); + } + } + break; + default: + close(presharedfd[1]); + + if (socketpair(PF_LOCAL, SOCK_STREAM, 0, hellofd) == -1) + err(EX_OSERR, "failed to create a 'hello' socket pair"); + + cmsg = CMSG_FIRSTHDR(&msg); + cmsg->cmsg_len = CMSG_LEN(sizeof(int)); + cmsg->cmsg_level = SOL_SOCKET; + cmsg->cmsg_type = SCM_RIGHTS; + *(int *)CMSG_DATA(cmsg) = hellofd[1]; + + if (sendmsg(presharedfd[0], &msg, 0) == -1) + err(EX_IOERR, "sendmsg"); + close(hellofd[1]); + + if (read(hellofd[0], buf, HELLOLEN) == -1) + err(EX_IOERR, "failed to receive 'hello'"); + printf("parent: received '%s'\\n", buf); + break; + } + + return (0); +} +.Ed +.Sh SEE ALSO +.Xr recvmsg 2 , +.Xr sendmsg 2 , +.Xr socket 2 , +.Xr ip 4 , +.Xr ip6 4 , +.Xr unix 4 +.Sh STANDARDS +.Bl -item +.It +.Rs +.%A W. Stevens +.%A M. Thomas +.%T "Advanced Sockets API for IPv6" +.%R RFC 2292 +.%D February 1998 +.Re +.It +.Rs +.%A W. Stevens +.%A M. Thomas +.%A E. Nordmark +.%A T. Jinmei +.%T "Advanced Sockets Application Program Interface (API) for IPv6" +.%R RFC 3542 +.%D May 2003 +.Re +.El +.Sh HISTORY +The control message API first appeared in +.Bx 4.2 . +This manual page was originally written by +.An Jared Yanovich Aq Mt jaredy@OpenBSD.org +for +.Ox 3.8 +and eventually brought to +.Fx 12.0 +by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . diff --git a/static/freebsd/man3/Makefile b/static/freebsd/man3/Makefile new file mode 100644 index 00000000..c070e829 --- /dev/null +++ b/static/freebsd/man3/Makefile @@ -0,0 +1,3 @@ +MAN = $(wildcard *.3) + +include ../../mandoc.mk diff --git a/static/freebsd/man3/Q_FRAWMASK.3 b/static/freebsd/man3/Q_FRAWMASK.3 new file mode 100644 index 00000000..4d03b259 --- /dev/null +++ b/static/freebsd/man3/Q_FRAWMASK.3 @@ -0,0 +1,123 @@ +.\" +.\" Copyright (c) 2018 Netflix, Inc. +.\" 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, +.\" without modification, immediately at the beginning of the file. +.\" 2. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR +.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 8, 2018 +.Dt Q_FRAWMASK 3 +.Os +.Sh NAME +.Nm Q_FRAWMASK , +.Nm Q_GFRAW , +.Nm Q_GFABSVAL , +.Nm Q_GFVAL , +.Nm Q_SFVAL +.Nd fixed-point math functions which manipulate the fractional data bits +.Sh SYNOPSIS +.In sys/qmath.h +.Ft ITYPE +.Fn Q_FRAWMASK "QTYPE q" +.Ft ITYPE +.Fn Q_GFRAW "QTYPE q" +.Ft ITYPE +.Fn Q_GFABSVAL "QTYPE q" +.Ft ITYPE +.Fn Q_GFVAL "QTYPE q" +.Ft QTYPE +.Fn Q_SFVAL "QTYPE q" "ITYPE fv" +.Sh DESCRIPTION +.Fn Q_FRAWMASK +returns a +.Fa q Ns -specific +bit mask for +.Fa q Ap s +fractional data bits. +.Pp +.Fn Q_GFRAW +returns +.Fa q Ap s +raw masked fractional data bits. +.Pp +.Fn Q_GFABSVAL +and +.Fn Q_GFVAL +return the absolute and real values of +.Fa q Ap s +fractional data bits respectively. +.Pp +.Fn Q_SFVAL +sets +.Fa q Ap s +fractional data bits to the value +.Fa fv . +.Pp +All of those functions operate on +the following data types: +.Vt s8q_t , +.Vt u8q_t , +.Vt s16q_t , +.Vt u16q_t , +.Vt s32q_t , +.Vt u32q_t , +.Vt s64q_t , +and +.Vt u64q_t , +which are referred to generically as +.Fa QTYPE . +The +.Fa ITYPE +refers to the +.Xr stdint 7 +integer types. +.Pp +For more details, see +.Xr qmath 3 . +.Sh RETURN VALUES +.Fn Q_FRAWMASK , +.Fn Q_GFRAW , +.Fn Q_GFABSVAL +and +.Fn Q_GFVAL +return their respective values as integers of the same underlying ITYPE as +.Fa q . +.Pp +.Fn Q_SFVAL +returns the value of +.Fa q +post set. +.Sh SEE ALSO +.Xr errno 2 , +.Xr qmath 3 , +.Xr stdint 7 +.Sh HISTORY +The +.Xr qmath 3 +functions first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Xr qmath 3 +functions and this manual page were written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and sponsored by Netflix, Inc. diff --git a/static/freebsd/man3/Q_IFRAWMASK.3 b/static/freebsd/man3/Q_IFRAWMASK.3 new file mode 100644 index 00000000..b6885084 --- /dev/null +++ b/static/freebsd/man3/Q_IFRAWMASK.3 @@ -0,0 +1,160 @@ +.\" +.\" Copyright (c) 2018 Netflix, Inc. +.\" 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, +.\" without modification, immediately at the beginning of the file. +.\" 2. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR +.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 8, 2018 +.Dt Q_IFRAWMASK 3 +.Os +.Sh NAME +.Nm Q_IFRAWMASK , +.Nm Q_IFVALIMASK , +.Nm Q_IFVALFMASK , +.Nm Q_GIFRAW , +.Nm Q_GIFABSVAL , +.Nm Q_GIFVAL , +.Nm Q_SIFVAL , +.Nm Q_SIFVALS +.Nd fixed-point math functions which manipulate the combined integer/fractional +data bits +.Sh SYNOPSIS +.In sys/qmath.h +.Ft ITYPE +.Fn Q_IFRAWMASK "QTYPE q" +.Ft ITYPE +.Fn Q_IFVALIMASK "QTYPE q" +.Ft ITYPE +.Fn Q_IFVALFMASK "QTYPE q" +.Ft ITYPE +.Fn Q_GIFRAW "QTYPE q" +.Ft ITYPE +.Fn Q_GIFABSVAL "QTYPE q" +.Ft ITYPE +.Fn Q_GIFVAL "QTYPE q" +.Ft QTYPE +.Fn Q_SIFVAL "QTYPE q" "ITYPE ifv" +.Ft QTYPE +.Fn Q_SIFVALS "QTYPE q" "ITYPE iv" "ITYPE fv" +.Sh DESCRIPTION +.Fn Q_IFRAWMASK +returns a +.Fa q Ns -specific +bit mask for +.Fa q Ap s +combined integer and fractional data bits. +.Pp +.Fn Q_IFVALIMASK +and +.Fn Q_IFVALFMASK +return +.Fa q Ns -specific +bit masks for the integer and fractional bits of +.Fa q Ap s +combined integer and fractional data bits value, i.e., are applicable to the +values returned by +.Fn Q_GIFABSVAL +and +.Fn Q_GIFVAL . +.Pp +.Fn Q_GIFRAW +returns +.Fa q Ap s +raw masked integer/fractional data bits. +.Pp +.Fn Q_GIFABSVAL +and +.Fn Q_GIFVAL +return the absolute and real values of +.Fa q Ap s +integer/fractional data bits respectively. +.Pp +.Fn Q_SIFVAL +sets +.Fa q Ap s +combined integer/fractional data bits to the value +.Fa ifv , +whereas +.Fn Q_SIFVALS +independently sets +.Fa q Ap s +integer and fractional data bits to the separate values +.Fa iv +and +.Fa fv . +.Pp +All of those functions operate on +the following data types: +.Vt s8q_t , +.Vt u8q_t , +.Vt s16q_t , +.Vt u16q_t , +.Vt s32q_t , +.Vt u32q_t , +.Vt s64q_t , +and +.Vt u64q_t , +which are referred to generically as +.Fa QTYPE . +The +.Fa ITYPE +refers to the +.Xr stdint 7 +integer types. +.Pp +For more details, see +.Xr qmath 3 . +.Sh RETURN VALUES +.Fn Q_IFRAWMASK , +.Fn Q_IFVALIMASK , +.Fn Q_IFVALFMASK , +.Fn Q_GIFABSVAL , +.Fn Q_GIFVAL , +.Fn Q_GIFRAW , +.Fn Q_GIFABSVAL +and +.Fn Q_GIFVAL +return their respective values as integers of the same underlying ITYPE as +.Fa q . +.Pp +.Fn Q_SIFVAL +and +.Fn Q_SIFVALS +return the value of +.Fa q +post change. +.Sh SEE ALSO +.Xr errno 2 , +.Xr qmath 3 , +.Xr stdint 7 +.Sh HISTORY +The +.Xr qmath 3 +functions first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Xr qmath 3 +functions and this manual page were written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and sponsored by Netflix, Inc. diff --git a/static/freebsd/man3/Q_INI.3 b/static/freebsd/man3/Q_INI.3 new file mode 100644 index 00000000..b7794d72 --- /dev/null +++ b/static/freebsd/man3/Q_INI.3 @@ -0,0 +1,259 @@ +.\" +.\" Copyright (c) 2018 Netflix, Inc. +.\" 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, +.\" without modification, immediately at the beginning of the file. +.\" 2. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR +.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 8, 2018 +.Dt Q_INI 3 +.Os +.Sh NAME +.Nm Q_INI , +.Nm Q_NCBITS , +.Nm Q_BT , +.Nm Q_TC , +.Nm Q_NTBITS , +.Nm Q_NFCBITS , +.Nm Q_MAXNFBITS , +.Nm Q_NFBITS , +.Nm Q_NIBITS , +.Nm Q_RPSHFT , +.Nm Q_ABS , +.Nm Q_MAXSTRLEN , +.Nm Q_TOSTR , +.Nm Q_SHL , +.Nm Q_SHR , +.Nm Q_DEBUG +.Nd fixed-point math miscellaneous functions/variables +.Sh SYNOPSIS +.In sys/qmath.h +.Ft QTYPE +.Fn Q_INI "QTYPE *q" "ITYPE iv" "ITYPE dfv" "int rpshft" +.Fd Q_NCBITS +.Ft __typeof(q) +.Fn Q_BT "QTYPE q" +.Ft ITYPE +.Fn Q_TC "QTYPE q" "ITYPE v" +.Ft uint32_t +.Fn Q_NTBITS "QTYPE q" +.Ft uint32_t +.Fn Q_NFCBITS "QTYPE q" +.Ft uint32_t +.Fn Q_MAXNFBITS "QTYPE q" +.Ft uint32_t +.Fn Q_NFBITS "QTYPE q" +.Ft uint32_t +.Fn Q_NIBITS "QTYPE q" +.Ft uint32_t +.Fn Q_RPSHFT "QTYPE q" +.Ft NTYPE +.Fn Q_ABS "NTYPE n" +.Ft uint32_t +.Fn Q_MAXSTRLEN "QTYPE q" "int base" +.Ft char * +.Fn Q_TOSTR "QTYPE q" "int prec" "int base" "char *s" "int slen" +.Ft ITYPE +.Fn Q_SHL "QTYPE q" "ITYPE iv" +.Ft ITYPE +.Fn Q_SHR "QTYPE q" "ITYPE iv" +.Ft char *, ... +.Fn Q_DEBUG "QTYPE q" "char *prefmt" "char *postfmt" "incfmt" +.Ft ITYPE +.Fn Q_DFV2BFV "ITYPE dfv" "int nfbits" +.Sh DESCRIPTION +.Fn Q_INI +initialises a Q number with the supplied integral value +.Fa iv +and decimal fractional value +.Fa dfv , +with appropriate control bits based on the requested radix shift point +.Fa rpshft . +.Fa dfv +must be passed as a preprocessor literal to preserve leading zeroes. +.Pp +The +.Dv Q_NCBITS +defined constant specifies the number of reserved control bits, currently 3. +.Pp +.Fn Q_NTBITS , +.Fn Q_NFCBITS , +.Fn Q_MAXNFBITS , +.Fn Q_NFBITS +and +.Fn Q_NIBITS +return the +.Fa q Ns -specific +count of total, control-encoded fractional, maximum fractional, effective +fractional, and integer bits applicable to +.Fa q +respectively. +.Pp +.Fn Q_BT +returns the C data type of +.Fa q , +while +.Fn Q_TC +returns +.Fa v +type casted to the C data type of +.Fa q . +.Pp +.Fn Q_RPSHFT +returns the bit position of +.Fa q Ap s +binary radix point relative to bit zero. +.Pp +.Fn Q_ABS +returns the absolute value of any standard numeric type +.Pq that uses the MSB as a sign bit, but not Q numbers +passed in as +.Fa n . +The function is signed/unsigned type safe. +.Pp +.Fn Q_SHL +and +.Fn Q_SHR +return the integral value +.Fa v +left or right shifted by the appropriate amount for +.Fa q . +.Pp +.Fn Q_MAXSTRLEN +calculates the maximum number of characters that may be required to render the +C-string representation of +.Fa q +with numeric base +.Fa base . +.Pp +.Fn Q_TOSTR +renders the C-string representation of +.Fa q +with numeric base +.Fa base +and fractional precision +.Fa prec +into +.Fa s +which has an available capacity of +.Fa slen +characters. +.Fa base +must be in range +.Bq 2,16 . +Specifying +.Fa prec +as -1 renders the number's fractional component with maximum precision. +If +.Fa slen +is greater than zero but insufficient to hold the complete C-string, the '\\0' +C-string terminator will be written to +.Fa *s , +thereby returning a zero length C-string. +.Pp +.Fn Q_DEBUG +returns a format string and associated data suitable for printf-like rendering +of debugging information pertaining to +.Fa q . +If either +.Fa prefmt +and/or +.Fa postfmt +are specified, they are prepended and appended to the resulting format string +respectively. +The +.Fa incfmt +boolean specifies whether to include +.Pq Vt true +or exclude +.Pq Vt false +the raw format string itself in the debugging output. +.Pp +.Fn Q_DFV2BFV +converts decimal fractional value +.Fa dfv +to its binary-encoded representation with +.Fa nfbits +of binary precision. +.Fa dfv +must be passed as a preprocessor literal to preserve leading zeroes. +The returned value can be used to set a Q number's fractional bits, for example +using +.Fn Q_SFVAL . +.Pp +All of those functions operate on +the following data types: +.Vt s8q_t , +.Vt u8q_t , +.Vt s16q_t , +.Vt u16q_t , +.Vt s32q_t , +.Vt u32q_t , +.Vt s64q_t , +and +.Vt u64q_t , +which are referred to generically as +.Fa QTYPE . +The +.Fa ITYPE +refers to the +.Xr stdint 7 +integer types. +.Fa NTYPE +is used to refer to any numeric type and is therefore a superset of +.Fa QTYPE +and +.Fa ITYPE . +.Pp +For more details, see +.Xr qmath 3 . +.Sh RETURN VALUES +.Fn Q_INI +returns the initialised Q number which can be used to chain initialise +additional Q numbers. +.Pp +.Fn Q_TOSTR +returns a pointer to the '\\0' C-string terminator appended to +.Fa s +after the rendered numeric data, or NULL on buffer overflow. +.Pp +.Fn Q_DFV2BFV +returns the binary-encoded representation of decimal fractional value +.Fa dfv +with +.Fa nfbits +of binary precision. +.Sh SEE ALSO +.Xr errno 2 , +.Xr qmath 3 , +.Xr stdint 7 +.Sh HISTORY +The +.Xr qmath 3 +functions first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Xr qmath 3 +functions and this manual page were written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and sponsored by Netflix, Inc. diff --git a/static/freebsd/man3/Q_IRAWMASK.3 b/static/freebsd/man3/Q_IRAWMASK.3 new file mode 100644 index 00000000..a15b885c --- /dev/null +++ b/static/freebsd/man3/Q_IRAWMASK.3 @@ -0,0 +1,123 @@ +.\" +.\" Copyright (c) 2018 Netflix, Inc. +.\" 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, +.\" without modification, immediately at the beginning of the file. +.\" 2. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR +.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 8, 2018 +.Dt Q_IRAWMASK 3 +.Os +.Sh NAME +.Nm Q_IRAWMASK , +.Nm Q_GIRAW , +.Nm Q_GIABSVAL , +.Nm Q_GIVAL , +.Nm Q_SIVAL +.Nd fixed-point math functions which manipulate the integer data bits +.Sh SYNOPSIS +.In sys/qmath.h +.Ft ITYPE +.Fn Q_IRAWMASK "QTYPE q" +.Ft ITYPE +.Fn Q_GIRAW "QTYPE q" +.Ft ITYPE +.Fn Q_GIABSVAL "QTYPE q" +.Ft ITYPE +.Fn Q_GIVAL "QTYPE q" +.Ft QTYPE +.Fn Q_SIVAL "QTYPE q" "ITYPE iv" +.Sh DESCRIPTION +.Fn Q_IRAWMASK +returns a +.Fa q Ns -specific +bit mask for +.Fa q Ap s +integer data bits. +.Pp +.Fn Q_GIRAW +returns +.Fa q Ap s +raw masked integer data bits. +.Pp +.Fn Q_GIABSVAL +and +.Fn Q_GIVAL +return the absolute and real values of +.Fa q Ap s +integer data bits respectively. +.Pp +.Fn Q_SIVAL +sets +.Fa q Ap s +integer data bits to the value +.Fa iv . +.Pp +All of those functions operate on +the following data types: +.Vt s8q_t , +.Vt u8q_t , +.Vt s16q_t , +.Vt u16q_t , +.Vt s32q_t , +.Vt u32q_t , +.Vt s64q_t , +and +.Vt u64q_t , +which are referred to generically as +.Fa QTYPE . +The +.Fa ITYPE +refers to the +.Xr stdint 7 +integer types. +.Pp +For more details, see +.Xr qmath 3 . +.Sh RETURN VALUES +.Fn Q_IRAWMASK , +.Fn Q_GIRAW , +.Fn Q_GIABSVAL +and +.Fn Q_GIVAL +return their respective values as integers of the same underlying ITYPE as +.Fa q . +.Pp +.Fn Q_SIVAL +returns the value of +.Fa q +post change. +.Sh SEE ALSO +.Xr errno 2 , +.Xr qmath 3 , +.Xr stdint 7 +.Sh HISTORY +The +.Xr qmath 3 +functions first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Xr qmath 3 +functions and this manual page were written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and sponsored by Netflix, Inc. diff --git a/static/freebsd/man3/Q_QABS.3 b/static/freebsd/man3/Q_QABS.3 new file mode 100644 index 00000000..31219e1f --- /dev/null +++ b/static/freebsd/man3/Q_QABS.3 @@ -0,0 +1,99 @@ +.\" +.\" Copyright (c) 2018 Netflix, Inc. +.\" 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, +.\" without modification, immediately at the beginning of the file. +.\" 2. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR +.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 8, 2018 +.Dt Q_QABS 3 +.Os +.Sh NAME +.Nm Q_QABS , +.Nm Q_Q2S , +.Nm Q_Q2F +.Nd fixed-point math functions which operate on a single Q number +.Sh SYNOPSIS +.In sys/qmath.h +.Ft QTYPE +.Fn Q_QABS "QTYPE q" +.Ft double +.Fn Q_Q2D "QTYPE q" +.Ft float +.Fn Q_Q2F "QTYPE q" +.Sh DESCRIPTION +The +.Fn Q_QABS +function returns an absolute value representation of +.Fa q . +.Pp +The +.Fn Q_Q2D +and +.Fn Q_Q2F +functions return the double and float representations of +.Fa q +respectively. +.Pp +All of those functions operate on +the following data types: +.Vt s8q_t , +.Vt u8q_t , +.Vt s16q_t , +.Vt u16q_t , +.Vt s32q_t , +.Vt u32q_t , +.Vt s64q_t , +and +.Vt u64q_t , +which are referred to generically as +.Fa QTYPE . +.Pp +For more details, see +.Xr qmath 3 . +.Sh RETURN VALUES +.Fn Q_QABS +function returns a QTYPE that is identical to that of +.Fa q . +.Pp +The +.Fn Q_Q2D +and +.Fn Q_Q2F +functions return the double and float representations of +.Fa q +respectively. +.Sh SEE ALSO +.Xr errno 2 , +.Xr qmath 3 , +.Xr stdint 7 +.Sh HISTORY +The +.Xr qmath 3 +functions first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Xr qmath 3 +functions and this manual page were written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and sponsored by Netflix, Inc. diff --git a/static/freebsd/man3/Q_QADDI.3 b/static/freebsd/man3/Q_QADDI.3 new file mode 100644 index 00000000..5b1bc8c2 --- /dev/null +++ b/static/freebsd/man3/Q_QADDI.3 @@ -0,0 +1,132 @@ +.\" +.\" Copyright (c) 2018 Netflix, Inc. +.\" 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, +.\" without modification, immediately at the beginning of the file. +.\" 2. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR +.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 8, 2018 +.Dt Q_QADDI 3 +.Os +.Sh NAME +.Nm Q_QADDI , +.Nm Q_QDIVI , +.Nm Q_QMULI , +.Nm Q_QSUBI , +.Nm Q_QFRACI , +.Nm Q_QCPYVALI +.Nd fixed-point math functions which apply integers to a Q number +.Sh SYNOPSIS +.In sys/qmath.h +.Ft int +.Fn Q_QADDI "QTYPE *a" "ITYPE b" +.Ft int +.Fn Q_QDIVI "QTYPE *a" "ITYPE b" +.Ft int +.Fn Q_QMULI "QTYPE *a" "ITYPE b" +.Ft int +.Fn Q_QSUBI "QTYPE *a" "ITYPE b" +.Ft int +.Fn Q_QFRACI "QTYPE *q" "ITYPE n" "ITYPE d" +.Ft int +.Fn Q_QCPYVALI "QTYPE *q" "ITYPE i" +.Sh DESCRIPTION +The +.Fn Q_QADDI , +.Fn Q_QDIVI , +.Fn Q_QMULI +and +.Fn Q_QSUBI +functions add, divide, multiply or subtract +.Fa b +to/by/from +.Fa a +respectively, storing the result in +.Fa a . +.Pp +The +.Fn Q_QFRACI +function computes the fraction +.Fa n +divided by +.Fa d +and stores the fixed-point result in +.Fa q . +.Pp +The +.Fn Q_QCPYVALI +function overwrites +.Fa q Ap s +integer and fractional bits with the Q representation of integer value +.Fa i . +.Pp +All of those functions operate on +the following data types: +.Vt s8q_t , +.Vt u8q_t , +.Vt s16q_t , +.Vt u16q_t , +.Vt s32q_t , +.Vt u32q_t , +.Vt s64q_t , +and +.Vt u64q_t , +which are referred to generically as +.Fa QTYPE . +The +.Fa ITYPE +refers to the +.Xr stdint 7 +integer types. +.Pp +For more details, see +.Xr qmath 3 . +.Sh RETURN VALUES +.Fn Q_QADDI , +.Fn Q_QDIVI , +.Fn Q_QMULI , +.Fn Q_QSUBI , +.Fn Q_QFRACI +and +.Fn Q_QCPYVALI +functions return 0 on success, or an errno on failure. +.Er EINVAL +is returned for divide-by-zero. +.Er EOVERFLOW +and +.Er ERANGE +are returned for overflow and underflow respectively. +.Sh SEE ALSO +.Xr errno 2 , +.Xr qmath 3 , +.Xr stdint 7 +.Sh HISTORY +The +.Xr qmath 3 +functions first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Xr qmath 3 +functions and this manual page were written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and sponsored by Netflix, Inc. diff --git a/static/freebsd/man3/Q_QADDQ.3 b/static/freebsd/man3/Q_QADDQ.3 new file mode 100644 index 00000000..d6a7df7f --- /dev/null +++ b/static/freebsd/man3/Q_QADDQ.3 @@ -0,0 +1,173 @@ +.\" +.\" Copyright (c) 2018 Netflix, Inc. +.\" 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, +.\" without modification, immediately at the beginning of the file. +.\" 2. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR +.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 8, 2018 +.Dt Q_QADDQ 3 +.Os +.Sh NAME +.Nm Q_QADDQ , +.Nm Q_QDIVQ , +.Nm Q_QMULQ , +.Nm Q_QSUBQ , +.Nm Q_NORMPREC , +.Nm Q_QMAXQ , +.Nm Q_QMINQ , +.Nm Q_QCLONEQ , +.Nm Q_CPYVALQ +.Nd fixed-point math functions which operate on two Q numbers +.Sh SYNOPSIS +.In sys/qmath.h +.Ft int +.Fn Q_QADDQ "QTYPE *a" "QTYPE b" +.Ft int +.Fn Q_QDIVQ "QTYPE *a" "QTYPE b" +.Ft int +.Fn Q_QMULQ "QTYPE *a" "QTYPE b" +.Ft int +.Fn Q_QSUBQ "QTYPE *a" "QTYPE b" +.Ft int +.Fn Q_NORMPREC "QTYPE *a" "QTYPE *b" +.Ft QTYPE +.Fn Q_QMAXQ "QTYPE a" "QTYPE b" +.Ft QTYPE +.Fn Q_QMINQ "QTYPE a" "QTYPE b" +.Ft int +.Fn Q_QCLONEQ "QTYPE *l" "QTYPE r" +.Ft int +.Fn Q_QCPYVALQ "QTYPE *l" "QTYPE r" +.Sh DESCRIPTION +The +.Fn Q_QADDQ , +.Fn Q_QDIVQ , +.Fn Q_QMULQ , +and +.Fn Q_QSUBQ +functions add, divide, multiply or subtract +.Fa b +to/by/from +.Fa a +respectively, storing the result in +.Fa a . +Both arguments must be initialized with the same fractional radix point. +.Pp +The +.Fn Q_NORMPREC +function attempts to normalise the precision of +.Fa a +and +.Fa b +if they differ. +The greater of the two precisions is preferred if possible, unless that would +truncate integer component data for the other operand, in which case the highest +precision that preserves the integer component of both +.Fa a +and +.Fa b +is selected. +.Pp +The +.Fn Q_QMAXQ +and +.Fn Q_QMINQ +functions return the larger or smaller of +.Fa a +and +.Fa b +respectively. +.Pp +The +.Fn Q_QCLONEQ +and +.Fn Q_QCPYVALQ +functions attempt to store identical or representational copies of +.Fa r , +in +.Fa l +respectively. +An identical Q number produced by cloning copies the control bits as well as the +verbatim integer/fractional bits. +A representational copy only copies the values of +.Fa r Ap s +integer and fractional bits, representing them in the bits available per +.Fa l Ap s +Q format. +.Pp +All of those functions operate on the following data types: +.Vt s8q_t , +.Vt u8q_t , +.Vt s16q_t , +.Vt u16q_t , +.Vt s32q_t , +.Vt u32q_t , +.Vt s64q_t , +and +.Vt u64q_t , +which are referred to generically as +.Fa QTYPE . +.Pp +For more details, see +.Xr qmath 3 . +.Sh RETURN VALUES +The +.Fn Q_QADDQ , +.Fn Q_QDIVQ , +.Fn Q_QMULQ , +.Fn Q_QSUBQ +.Fn Q_NORMPREC , +.Fn Q_QCLONEQ +and +.Fn Q_QCPYVALQ +functions return 0 on success, or an errno on failure. +.Er EINVAL +is returned for divide-by-zero. +.Er EOVERFLOW +and +.Er ERANGE +are returned for overflow and underflow respectively. +.Er ERANGE is also returned when the precision of arguments +does not match. +.Pp +The +.Fn Q_QMAXQ +and +.Fn Q_QMINQ +functions return the numerically larger or smaller of their two inputs +respectively. +.Sh SEE ALSO +.Xr errno 2 , +.Xr qmath 3 , +.Xr stdint 7 +.Sh HISTORY +The +.Xr qmath 3 +functions first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Xr qmath 3 +functions and this manual page were written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and sponsored by Netflix, Inc. diff --git a/static/freebsd/man3/Q_SIGNED.3 b/static/freebsd/man3/Q_SIGNED.3 new file mode 100644 index 00000000..528757dc --- /dev/null +++ b/static/freebsd/man3/Q_SIGNED.3 @@ -0,0 +1,208 @@ +.\" +.\" Copyright (c) 2018 Netflix, Inc. +.\" 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, +.\" without modification, immediately at the beginning of the file. +.\" 2. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR +.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 8, 2018 +.Dt Q_SIGNED 3 +.Os +.Sh NAME +.Nm Q_SIGNED , +.Nm Q_LTZ , +.Nm Q_PRECEQ , +.Nm Q_QLTQ , +.Nm Q_QLEQ , +.Nm Q_QGTQ , +.Nm Q_QGEQ , +.Nm Q_QEQ , +.Nm Q_QNEQ , +.Nm Q_OFLOW , +.Nm Q_RELPREC +.Nd fixed-point math comparison and logic functions +.Sh SYNOPSIS +.In sys/qmath.h +.Ft bool +.Fn Q_SIGNED "NTYPE n" +.Ft bool +.Fn Q_LTZ "NTYPE n" +.Ft bool +.Fn Q_PRECEQ "QTYPE a" "QTYPE b" +.Ft bool +.Fn Q_QLTQ "QTYPE a" "QTYPE b" +.Ft bool +.Fn Q_QLEQ "QTYPE a" "QTYPE b" +.Ft bool +.Fn Q_QGTQ "QTYPE a" "QTYPE b" +.Ft bool +.Fn Q_QGEQ "QTYPE a" "QTYPE b" +.Ft bool +.Fn Q_QEQ "QTYPE a" "QTYPE b" +.Ft bool +.Fn Q_QNEQ "QTYPE a" "QTYPE b" +.Ft bool +.Fn Q_OFLOW "QTYPE q" "ITYPE iv" +.Ft int +.Fn Q_RELPREC "QTYPE a" "QTYPE b" +.Sh DESCRIPTION +.Fn Q_SIGNED +returns +.Ft true +if the numeric data type passed in as +.Fa n +is signed, or +.Ft false +otherwise. +.Pp +.Fn Q_LTZ +returns +.Ft true +if the numeric value +passed in as +.Fa n +is negative +.Pq requires types which use the MSB as the sign bit , +or +.Ft false +otherwise. +.Pp +.Fn Q_PRECEQ +returns +.Ft true +if the number of +.Fa a +and +.Fa b +fractional bits is the same, +.Ft false +otherwise. +.Pp +The +.Fn Q_QLTQ , +.Fn Q_QLEQ , +.Fn Q_QGTQ , +.Fn Q_QGEQ , +.Fn Q_QEQ +and +.Fn Q_QNEQ +functions compare two Q numbers, returning +.Ft true +if +.Fa a +is less than, less than or equal to, greater than, greater than or equal to, +equal to, or not equal to +.Fa b +respectively, or +.Ft false +otherwise. +The integral and fractional values are used to perform the comparison, without +explicit concern for the underlying number of integer versus fractional bits. +.Pp +.Fn Q_OFLOW +returns +.Ft true +if integer value +.Fa iv +cannot be stored in +.Fa q +without truncation, or false otherwise. +.Pp +.Fn Q_RELPREC +returns the relative precision of +.Fa a +versus +.Fa b . +In terms of +.Em Qm.n +notation, this function returns the difference between the +.Em n +values of +.Fa a +and +.Fa b . +For example, a return value of +4 means that +.Fa a +has an additional 4 bits of fractional precision compared to +.Fa b . +.Pp +All of those functions operate on +the following data types: +.Vt s8q_t , +.Vt u8q_t , +.Vt s16q_t , +.Vt u16q_t , +.Vt s32q_t , +.Vt u32q_t , +.Vt s64q_t , +and +.Vt u64q_t , +which are referred to generically as +.Fa QTYPE . +The +.Fa ITYPE +refers to the +.Xr stdint 7 +integer types. +.Fa NTYPE +is used to refer to any numeric type and is therefore a superset of +.Fa QTYPE +and +.Fa ITYPE . +.Pp +For more details, see +.Xr qmath 3 . +.Sh RETURN VALUES +The +.Fn Q_SIGNED , +.Fn Q_LTZ , +.Fn Q_PRECEQ , +.Fn Q_QLTQ , +.Fn Q_QLEQ , +.Fn Q_QGTQ , +.Fn Q_QGEQ , +.Fn Q_QEQ , +.Fn Q_QNEQ +and +.Fn Q_OFLOW +functions return expressions that evaluate to boolean +.Vt true +or +.Vt false . +.Pp +.Fn Q_RELPREC +returns the relative precision difference as a signed integer. +.Sh SEE ALSO +.Xr errno 2 , +.Xr qmath 3 , +.Xr stdint 7 +.Sh HISTORY +The +.Xr qmath 3 +functions first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Xr qmath 3 +functions and this manual page were written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and sponsored by Netflix, Inc. diff --git a/static/freebsd/man3/Q_SIGNSHFT.3 b/static/freebsd/man3/Q_SIGNSHFT.3 new file mode 100644 index 00000000..ce355560 --- /dev/null +++ b/static/freebsd/man3/Q_SIGNSHFT.3 @@ -0,0 +1,145 @@ +.\" +.\" Copyright (c) 2018 Netflix, Inc. +.\" 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, +.\" without modification, immediately at the beginning of the file. +.\" 2. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR +.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 8, 2018 +.Dt Q_SIGNSHFT 3 +.Os +.Sh NAME +.Nm Q_SIGNSHFT , +.Nm Q_SSIGN , +.Nm Q_CRAWMASK , +.Nm Q_SRAWMASK , +.Nm Q_GCRAW , +.Nm Q_GCVAL , +.Nm Q_SCVAL +.Nd fixed-point math functions which manipulate the control/sign data bits +.Sh SYNOPSIS +.In sys/qmath.h +.Ft uint32_t +.Fn Q_SIGNSHFT "QTYPE q" +.Ft QTYPE +.Fn Q_SSIGN "QTYPE q" "bool isneg" +.Ft ITYPE +.Fn Q_CRAWMASK "QTYPE q" +.Ft ITYPE +.Fn Q_SRAWMASK "QTYPE q" +.Ft ITYPE +.Fn Q_GCRAW "QTYPE q" +.Ft ITYPE +.Fn Q_GCVAL "QTYPE q" +.Ft QTYPE +.Fn Q_SCVAL "QTYPE q" "ITYPE cv" +.Sh DESCRIPTION +.Fn Q_SIGNSHFT +gets the bit position of +.Fa q Ap s +sign bit relative to bit zero. +.Pp +.Fn Q_SSIGN +sets the sign bit of +.Fa q +based on the boolean +.Fa isneg . +.Pp +.Fn Q_CRAWMASK +and +.Fn Q_SRAWMASK +return +.Fa q Ns -specific +bit masks for +.Fa q Ap s +control bits and sign bit respectively. +.Pp +.Fn Q_GCRAW +and +.Fn Q_GCVAL +get the raw masked control bits and value of +.Fa q Ap s +control bits respectively. +.Pp +.Fn Q_SCVAL +sets +.Fa q Ap s +control bits to the value +.Fa cv . +.Pp +All of those functions operate on +the following data types: +.Vt s8q_t , +.Vt u8q_t , +.Vt s16q_t , +.Vt u16q_t , +.Vt s32q_t , +.Vt u32q_t , +.Vt s64q_t , +and +.Vt u64q_t , +which are referred to generically as +.Fa QTYPE . +The +.Fa ITYPE +refers to the +.Xr stdint 7 +integer types. +.Pp +For more details, see +.Xr qmath 3 . +.Sh RETURN VALUES +.Fn Q_SIGNSHFT +returns the sign bit's position as an integer. +.Pp +.Fn Q_SSIGN +returns the value of +.Fa q +post change. +.Pp +.Fn Q_CRAWMASK , +.Fn Q_SRAWMASK , +.Fn Q_GCRAW +and +.Fn Q_GCVAL +return their respective values as integers of the same underlying ITYPE as +.Fa q . +.Pp +.Fn Q_SCVAL +returns the value of +.Fa q +post change. +.Sh SEE ALSO +.Xr errno 2 , +.Xr qmath 3 , +.Xr stdint 7 +.Sh HISTORY +The +.Xr qmath 3 +functions first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Xr qmath 3 +functions and this manual page were written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and sponsored by Netflix, Inc. diff --git a/static/freebsd/man3/alloca.3 b/static/freebsd/man3/alloca.3 new file mode 100644 index 00000000..9e905d44 --- /dev/null +++ b/static/freebsd/man3/alloca.3 @@ -0,0 +1,101 @@ +.\" Copyright (c) 1980, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" Copyright (c) 2026 Aymeric Wibo <obiwac@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. +.\" 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 February 19, 2026 +.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 or macro allocates +.Fa size +bytes of space in the stack frame of the caller. +This temporary space is automatically freed on +return. +.Sh RETURN VALUES +.Fn alloca +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 +.Fn alloca +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 +.Fn alloca +is machine and compiler dependent; +its use is discouraged. +.Pp +.Fn alloca +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. +.Pp +The use of C99 variable-length arrays and +.Fn alloca +in the same function will cause the lifetime of +.Fn alloca Ns 's +storage to be limited to the block containing the +.Fn alloca . +For example, in the following snippet, +.Va p Ns 's +lifetime does not extend outside of the block, whereas it would've if +.Va vla +hadn't been defined or had been defined as a fixed-length array: +.Bd -literal -offset indent +char *p; +{ + const int n = 100; + int vla[n]; + p = alloca(32); + strcpy(p, "Hello, world!"); + printf("Inside: %s\\n", p); /* Valid. */ +} +printf("Outside: %s\\n", p); /* Undefined. */ +.Ed diff --git a/static/freebsd/man3/arb.3 b/static/freebsd/man3/arb.3 new file mode 100644 index 00000000..e33ef3a3 --- /dev/null +++ b/static/freebsd/man3/arb.3 @@ -0,0 +1,511 @@ +.\" $OpenBSD: tree.3,v 1.7 2002/06/12 01:09:20 provos Exp $ +.\" +.\" Copyright 2002 Niels Provos <provos@citi.umich.edu> +.\" Copyright 2018-2019 Netflix, Inc. +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by Niels Provos. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 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 October 14, 2019 +.Dt ARB 3 +.Os +.Sh NAME +.Nm ARB_PROTOTYPE , +.Nm ARB_PROTOTYPE_STATIC , +.Nm ARB_PROTOTYPE_INSERT , +.Nm ARB_PROTOTYPE_INSERT_COLOR , +.Nm ARB_PROTOTYPE_REMOVE , +.Nm ARB_PROTOTYPE_REMOVE_COLOR , +.Nm ARB_PROTOTYPE_FIND , +.Nm ARB_PROTOTYPE_NFIND , +.Nm ARB_PROTOTYPE_NEXT , +.Nm ARB_PROTOTYPE_PREV , +.Nm ARB_PROTOTYPE_MINMAX , +.Nm ARB_PROTOTYPE_REINSERT , +.Nm ARB_GENERATE , +.Nm ARB_GENERATE_STATIC , +.Nm ARB_GENERATE_INSERT , +.Nm ARB_GENERATE_INSERT_COLOR , +.Nm ARB_GENERATE_REMOVE , +.Nm ARB_GENERATE_REMOVE_COLOR , +.Nm ARB_GENERATE_FIND , +.Nm ARB_GENERATE_NFIND , +.Nm ARB_GENERATE_NEXT , +.Nm ARB_GENERATE_PREV , +.Nm ARB_GENERATE_MINMAX , +.Nm ARB_GENERATE_REINSERT , +.Nm ARB8_ENTRY , +.Nm ARB16_ENTRY , +.Nm ARB32_ENTRY , +.Nm ARB8_HEAD , +.Nm ARB16_HEAD , +.Nm ARB32_HEAD , +.Nm ARB_ALLOCSIZE , +.Nm ARB_INITIALIZER , +.Nm ARB_ROOT , +.Nm ARB_EMPTY , +.Nm ARB_FULL , +.Nm ARB_CURNODES , +.Nm ARB_MAXNODES , +.Nm ARB_NEXT , +.Nm ARB_PREV , +.Nm ARB_MIN , +.Nm ARB_MAX , +.Nm ARB_FIND , +.Nm ARB_NFIND , +.Nm ARB_LEFT , +.Nm ARB_LEFTIDX , +.Nm ARB_RIGHT , +.Nm ARB_RIGHTIDX , +.Nm ARB_PARENT , +.Nm ARB_PARENTIDX , +.Nm ARB_GETFREE , +.Nm ARB_FREEIDX , +.Nm ARB_FOREACH , +.Nm ARB_FOREACH_FROM , +.Nm ARB_FOREACH_SAFE , +.Nm ARB_FOREACH_REVERSE , +.Nm ARB_FOREACH_REVERSE_FROM , +.Nm ARB_FOREACH_REVERSE_SAFE , +.Nm ARB_INIT , +.Nm ARB_INSERT , +.Nm ARB_REMOVE , +.Nm ARB_REINSERT , +.Nm ARB_RESET_TREE +.Nd "array-based red-black trees" +.Sh SYNOPSIS +.In sys/arb.h +.Fn ARB_PROTOTYPE NAME TYPE FIELD CMP +.Fn ARB_PROTOTYPE_STATIC NAME TYPE FIELD CMP +.Fn ARB_PROTOTYPE_INSERT NAME TYPE ATTR +.Fn ARB_PROTOTYPE_INSERT_COLOR NAME TYPE ATTR +.Fn ARB_PROTOTYPE_REMOVE NAME TYPE ATTR +.Fn ARB_PROTOTYPE_REMOVE_COLOR NAME TYPE ATTR +.Fn ARB_PROTOTYPE_FIND NAME TYPE ATTR +.Fn ARB_PROTOTYPE_NFIND NAME TYPE ATTR +.Fn ARB_PROTOTYPE_NEXT NAME TYPE ATTR +.Fn ARB_PROTOTYPE_PREV NAME TYPE ATTR +.Fn ARB_PROTOTYPE_MINMAX NAME TYPE ATTR +.Fn ARB_PROTOTYPE_REINSERT NAME TYPE ATTR +.Fn ARB_GENERATE NAME TYPE FIELD CMP +.Fn ARB_GENERATE_STATIC NAME TYPE FIELD CMP +.Fn ARB_GENERATE_INSERT NAME TYPE FIELD CMP ATTR +.Fn ARB_GENERATE_INSERT_COLOR NAME TYPE FIELD ATTR +.Fn ARB_GENERATE_REMOVE NAME TYPE FIELD ATTR +.Fn ARB_GENERATE_REMOVE_COLOR NAME TYPE FIELD ATTR +.Fn ARB_GENERATE_FIND NAME TYPE FIELD CMP ATTR +.Fn ARB_GENERATE_NFIND NAME TYPE FIELD CMP ATTR +.Fn ARB_GENERATE_NEXT NAME TYPE FIELD ATTR +.Fn ARB_GENERATE_PREV NAME TYPE FIELD ATTR +.Fn ARB_GENERATE_MINMAX NAME TYPE FIELD ATTR +.Fn ARB_GENERATE_REINSERT NAME TYPE FIELD CMP ATTR +.Fn ARB<8|16|32>_ENTRY +.Fn ARB<8|16|32>_HEAD HEADNAME TYPE +.Ft "size_t" +.Fn ARB_ALLOCSIZE "ARB_HEAD *head" "int<8|16|32>_t maxnodes" "struct TYPE *elm" +.Fn ARB_INITIALIZER "ARB_HEAD *head" "int<8|16|32>_t maxnodes" +.Ft "struct TYPE *" +.Fn ARB_ROOT "ARB_HEAD *head" +.Ft "bool" +.Fn ARB_EMPTY "ARB_HEAD *head" +.Ft "bool" +.Fn ARB_FULL "ARB_HEAD *head" +.Ft "int<8|16|32>_t" +.Fn ARB_CURNODES "ARB_HEAD *head" +.Ft "int<8|16|32>_t" +.Fn ARB_MAXNODES "ARB_HEAD *head" +.Ft "struct TYPE *" +.Fn ARB_NEXT NAME "ARB_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn ARB_PREV NAME "ARB_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn ARB_MIN NAME "ARB_HEAD *head" +.Ft "struct TYPE *" +.Fn ARB_MAX NAME "ARB_HEAD *head" +.Ft "struct TYPE *" +.Fn ARB_FIND NAME "ARB_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn ARB_NFIND NAME "ARB_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn ARB_LEFT "struct TYPE *elm" "ARB_ENTRY NAME" +.Ft "int<8|16|32>_t" +.Fn ARB_LEFTIDX "struct TYPE *elm" "ARB_ENTRY NAME" +.Ft "struct TYPE *" +.Fn ARB_RIGHT "struct TYPE *elm" "ARB_ENTRY NAME" +.Ft "int<8|16|32>_t" +.Fn ARB_RIGHTIDX "struct TYPE *elm" "ARB_ENTRY NAME" +.Ft "struct TYPE *" +.Fn ARB_PARENT "struct TYPE *elm" "ARB_ENTRY NAME" +.Ft "int<8|16|32>_t" +.Fn ARB_PARENTIDX "struct TYPE *elm" "ARB_ENTRY NAME" +.Ft "struct TYPE *" +.Fn ARB_GETFREE "ARB_HEAD *head" "FIELD" +.Ft "int<8|16|32>_t" +.Fn ARB_FREEIDX "ARB_HEAD *head" +.Fn ARB_FOREACH VARNAME NAME "ARB_HEAD *head" +.Fn ARB_FOREACH_FROM "VARNAME" "NAME" "POS_VARNAME" +.Fn ARB_FOREACH_SAFE "VARNAME" "NAME" "ARB_HEAD *head" "TEMP_VARNAME" +.Fn ARB_FOREACH_REVERSE VARNAME NAME "ARB_HEAD *head" +.Fn ARB_FOREACH_REVERSE_FROM "VARNAME" "NAME" "POS_VARNAME" +.Fn ARB_FOREACH_REVERSE_SAFE "VARNAME" "NAME" "ARB_HEAD *head" "TEMP_VARNAME" +.Ft void +.Fn ARB_INIT "struct TYPE *elm" "FIELD" "ARB_HEAD *head" "int<8|16|32>_t maxnodes" +.Ft "struct TYPE *" +.Fn ARB_INSERT NAME "ARB_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn ARB_REMOVE NAME "ARB_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn ARB_REINSERT NAME "ARB_HEAD *head" "struct TYPE *elm" +.Ft void +.Fn ARB_RESET_TREE "ARB_HEAD *head" NAME "int<8|16|32>_t maxnodes" +.Sh DESCRIPTION +These macros define data structures for and array-based red-black trees. +They use a single, continuous chunk of memory, and are useful +e.g., when the tree needs to be transferred between userspace and kernel. +.Pp +In the macro definitions, +.Fa TYPE +is the name tag of a user defined structure that must contain a field of type +.Vt ARB_ENTRY , +named +.Fa ENTRYNAME . +The argument +.Fa HEADNAME +is the name tag of a user defined structure that must be declared +using the +.Fn ARB_HEAD +macro. +The argument +.Fa NAME +has to be a unique name prefix for every tree that is defined. +.Pp +The function prototypes are declared with +.Fn ARB_PROTOTYPE , +or +.Fn ARB_PROTOTYPE_STATIC . +The function bodies are generated with +.Fn ARB_GENERATE , +or +.Fn ARB_GENERATE_STATIC . +See the examples below for further explanation of how these macros are used. +.Pp +A red-black tree is a binary search tree with the node color as an +extra attribute. +It fulfills a set of conditions: +.Bl -enum -offset indent +.It +Every search path from the root to a leaf consists of the same number of +black nodes. +.It +Each red node (except for the root) has a black parent. +.It +Each leaf node is black. +.El +.Pp +Every operation on a red-black tree is bounded as +.Fn O "lg n" . +The maximum height of a red-black tree is +.Fn 2lg "n + 1" . +.Pp +.Fn ARB_* +trees require entries to be allocated as an array, and uses array +indices to link entries together. +The maximum number of +.Fn ARB_* +tree entries is therefore constrained by the minimum of array size and choice of +signed integer data type used to store array indices. +Use +.Fn ARB_ALLOCSIZE +to compute the size of memory chunk to allocate. +.Pp +A red-black tree is headed by a structure defined by the +.Fn ARB_HEAD +macro. +A +structure is declared with either of the following: +.Bd -ragged -offset indent +.Fn ARB<8|16|32>_HEAD HEADNAME TYPE +.Va head ; +.Ed +.Pp +where +.Fa HEADNAME +is the name of the structure to be defined, and struct +.Fa TYPE +is the type of the elements to be inserted into the tree. +.Pp +The +.Fn ARB_HEAD +variant includes a suffix denoting the signed integer data type size +.Pq in bits +used to store array indices. +For example, +.Fn ARB_HEAD8 +creates a red-black tree head structure with 8-bit signed array indices capable +of indexing up to 128 entries. +.Pp +The +.Fn ARB_ENTRY +macro declares a structure that allows elements to be connected in the tree. +Similarly to the +.Fn ARB<8|16|32>_HEAD +macro, the +.Fn ARB_ENTRY +variant includes a suffix denoting the signed integer data type size +.Pq in bits +used to store array indices. +Entries should use the same number of bits as the tree head structure they will +be linked into. +.Pp +In order to use the functions that manipulate the tree structure, +their prototypes need to be declared with the +.Fn ARB_PROTOTYPE +or +.Fn ARB_PROTOTYPE_STATIC +macro, +where +.Fa NAME +is a unique identifier for this particular tree. +The +.Fa TYPE +argument is the type of the structure that is being managed +by the tree. +The +.Fa FIELD +argument is the name of the element defined by +.Fn ARB_ENTRY . +Individual prototypes can be declared with +.Fn ARB_PROTOTYPE_INSERT , +.Fn ARB_PROTOTYPE_INSERT_COLOR , +.Fn ARB_PROTOTYPE_REMOVE , +.Fn ARB_PROTOTYPE_REMOVE_COLOR , +.Fn ARB_PROTOTYPE_FIND , +.Fn ARB_PROTOTYPE_NFIND , +.Fn ARB_PROTOTYPE_NEXT , +.Fn ARB_PROTOTYPE_PREV , +.Fn ARB_PROTOTYPE_MINMAX , +and +.Fn ARB_PROTOTYPE_REINSERT +in case not all functions are required. +The individual prototype macros expect +.Fa NAME , +.Fa TYPE , +and +.Fa ATTR +arguments. +The +.Fa ATTR +argument must be empty for global functions or +.Fa static +for static functions. +.Pp +The function bodies are generated with the +.Fn ARB_GENERATE +or +.Fn ARB_GENERATE_STATIC +macro. +These macros take the same arguments as the +.Fn ARB_PROTOTYPE +and +.Fn ARB_PROTOTYPE_STATIC +macros, but should be used only once. +As an alternative individual function bodies are generated with the +.Fn ARB_GENERATE_INSERT , +.Fn ARB_GENERATE_INSERT_COLOR , +.Fn ARB_GENERATE_REMOVE , +.Fn ARB_GENERATE_REMOVE_COLOR , +.Fn ARB_GENERATE_FIND , +.Fn ARB_GENERATE_NFIND , +.Fn ARB_GENERATE_NEXT , +.Fn ARB_GENERATE_PREV , +.Fn ARB_GENERATE_MINMAX , +and +.Fn ARB_GENERATE_REINSERT +macros. +.Pp +Finally, +the +.Fa CMP +argument is the name of a function used to compare tree nodes +with each other. +The function takes two arguments of type +.Vt "struct TYPE *" . +If the first argument is smaller than the second, the function returns a +value smaller than zero. +If they are equal, the function returns zero. +Otherwise, it should return a value greater than zero. +The compare +function defines the order of the tree elements. +.Pp +The +.Fn ARB_INIT +macro initializes the tree referenced by +.Fa head , +with the array length of +.Fa maxnodes . +.Pp +The red-black tree can also be initialized statically by using the +.Fn ARB_INITIALIZER +macro: +.Bd -ragged -offset indent +.Fn ARB<8|16|32>_HEAD HEADNAME TYPE +.Va head += +.Fn ARB_INITIALIZER &head maxnodes ; +.Ed +.Pp +The +.Fn ARB_INSERT +macro inserts the new element +.Fa elm +into the tree. +.Pp +The +.Fn ARB_REMOVE +macro removes the element +.Fa elm +from the tree pointed by +.Fa head . +.Pp +The +.Fn ARB_FIND +and +.Fn ARB_NFIND +macros can be used to find a particular element in the tree. +.Bd -literal -offset indent +struct TYPE find, *res; +find.key = 30; +res = ARB_FIND(NAME, head, &find); +.Ed +.Pp +The +.Fn ARB_ROOT , +.Fn ARB_MIN , +.Fn ARB_MAX , +.Fn ARB_NEXT , +and +.Fn ARB_PREV +macros can be used to traverse the tree: +.Pp +.Dl "for (np = ARB_MIN(NAME, &head); np != NULL; np = ARB_NEXT(NAME, &head, np))" +.Pp +Or, for simplicity, one can use the +.Fn ARB_FOREACH +or +.Fn ARB_FOREACH_REVERSE +macro: +.Bd -ragged -offset indent +.Fn ARB_FOREACH np NAME head +.Ed +.Pp +The macros +.Fn ARB_FOREACH_SAFE +and +.Fn ARB_FOREACH_REVERSE_SAFE +traverse the tree referenced by head +in a forward or reverse direction respectively, +assigning each element in turn to np. +However, unlike their unsafe counterparts, +they permit both the removal of np +as well as freeing it from within the loop safely +without interfering with the traversal. +.Pp +Both +.Fn ARB_FOREACH_FROM +and +.Fn ARB_FOREACH_REVERSE_FROM +may be used to continue an interrupted traversal +in a forward or reverse direction respectively. +The head pointer is not required. +The pointer to the node from where to resume the traversal +should be passed as their last argument, +and will be overwritten to provide safe traversal. +.Pp +The +.Fn ARB_EMPTY +macro should be used to check whether a red-black tree is empty. +.Pp +Given that ARB trees have an intrinsic upper bound on the number of entries, +some ARB-specific additional macros are defined. +The +.Fn ARB_FULL +macro returns a boolean indicating whether the current number of tree entries +equals the tree's maximum. +The +.Fn ARB_CURNODES +and +.Fn ARB_MAXNODES +macros return the current and maximum number of entries respectively. +The +.Fn ARB_GETFREE +macro returns a pointer to the next free entry in the array of entries, ready to +be linked into the tree. +The +.Fn ARB_INSERT +returns +.Dv NULL +if the element was inserted in the tree successfully, otherwise they +return a pointer to the element with the colliding key. +.Pp +Accordingly, +.Fn ARB_REMOVE +returns the pointer to the removed element otherwise they return +.Dv NULL +to indicate an error. +.Pp +The +.Fn ARB_REINSERT +macro updates the position of the element +.Fa elm +in the tree. +This must be called if a member of a +.Nm tree +is modified in a way that affects comparison, such as by modifying +a node's key. +This is a lower overhead alternative to removing the element +and reinserting it again. +.Pp +The +.Fn ARB_RESET_TREE +macro discards the tree topology. +It does not modify embedded object values or the free list. +.Sh SEE ALSO +.Xr queue 3 , +.Xr tree 3 +.Sh HISTORY +The +.Nm ARB +macros first appeared in +.Fx 13.0 . +.Sh AUTHORS +The +.Nm ARB +macros were implemented by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org , +based on +.Xr tree 3 +macros written by +.An Niels Provos . diff --git a/static/freebsd/man3/assert.3 b/static/freebsd/man3/assert.3 new file mode 100644 index 00000000..f219aa1d --- /dev/null +++ b/static/freebsd/man3/assert.3 @@ -0,0 +1,136 @@ +.\" Copyright (c) 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 20, 2021 +.Dt ASSERT 3 +.Os +.Sh NAME +.Nm assert , +.Nm static_assert +.Nd expression verification macro +.Sh SYNOPSIS +.In assert.h +.Fn assert expression +.Fn static_assert expression +.Fn static_assert expression message +.Sh DESCRIPTION +The +.Fn assert +macro tests the given +.Ar expression +and if it is false, +the calling process is terminated. +A diagnostic message is written to +.Dv stderr +and the function +.Xr abort 3 +is called, effectively terminating the program. +.Pp +If +.Ar expression +is true, +the +.Fn assert +macro does nothing. +.Pp +The +.Fn assert +macro +may be removed at compile time by defining +.Dv NDEBUG +as a macro +(e.g., by using the +.Xr cc 1 +option +.Fl D Ns Dv NDEBUG ) . +Unlike most other include files, +.In assert.h +may be included multiple times. +Each time whether or not +.Dv NDEBUG +is defined determines the behavior of assert from that point forward +until the end of the unit or another include of +.In assert.h . +.Pp +The +.Fn assert +macro should only be used for ensuring the developer's expectations +hold true. +It is not appropriate for regular run-time error detection. +.Pp +The +.Fn static_assert +macro expands to +.Fn _Static_assert , +and, contrarily to +.Fn assert , +makes assertions at compile-time. +Once the constraint is violated, the compiler produces a diagnostic +message including the string literal message, if provided. +The initial form of the +.Fn _Static_assert +containing a string literal message was introduced in C11 standard, and +the other form with no string literal is to be implemented by C2x and +some compilers may lack its adoption at present. +.Sh EXAMPLES +The assertion: +.Dl "assert(1 == 0);" +generates a diagnostic message similar to the following: +.Dl "Assertion failed: (1 == 0), function main, file main.c, line 100." +.Pp +The following assert tries to assert there was no partial read: +.Dl "assert(read(fd, buf, nbytes) == nbytes);" +However, there are two problems. +First, it checks for normal conditions, rather than conditions that +indicate a bug. +Second, the code will disappear if +.Dv NDEBUG +is defined, changing the semantics of the program. +.Pp +The following asserts that the size of the S structure is 16. +Otherwise, it produces a diagnostic message which points at the +constraint and includes the provided string literal: +.Dl "static_assert(sizeof(struct S) == 16, ""size mismatch"");" +If none is provided, it only points at the constraint. +.Sh SEE ALSO +.Xr abort2 2 , +.Xr abort 3 +.Sh STANDARDS +The +.Fn assert +macro conforms to +.St -isoC-99 . +.Pp +The +.Fn static_assert +macro conforms to +.St -isoC-2011 . +.Sh HISTORY +An +.Nm +macro appeared in +.At v7 . diff --git a/static/freebsd/man3/bitstring.3 b/static/freebsd/man3/bitstring.3 new file mode 100644 index 00000000..87ba9a24 --- /dev/null +++ b/static/freebsd/man3/bitstring.3 @@ -0,0 +1,470 @@ +.\" Copyright (c) 1989, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" Paul Vixie. +.\" 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. +.\" +.\" Copyright (c) 2014,2016 Spectra Logic Corporation +.\" 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, +.\" without modification. +.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer +.\" substantially similar to the "NO WARRANTY" disclaimer below +.\" ("Disclaimer") and any redistribution must be conditioned upon +.\" including a substantially similar Disclaimer requirement for further +.\" binary redistribution. +.\" +.\" NO WARRANTY +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR 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 DAMAGES. +.\" +.Dd November 21, 2023 +.Dt BITSTRING 3 +.Os +.Sh NAME +.Nm bit_alloc , +.Nm bit_clear , +.Nm bit_count , +.Nm bit_decl , +.Nm bit_ffc , +.Nm bit_ffs , +.Nm bit_ff_at , +.Nm bit_ffc_at , +.Nm bit_ffs_at , +.Nm bit_ffc_area , +.Nm bit_ffs_area , +.Nm bit_ff_area_at , +.Nm bit_ffc_area_at , +.Nm bit_ffs_area_at , +.Nm bit_nclear , +.Nm bit_nset , +.Nm bit_ntest , +.Nm bit_set , +.Nm bit_test , +.Nm bitstr_size +.Nd bit-string manipulation functions and macros +.Sh SYNOPSIS +.In bitstring.h +.Ft bitstr_t * +.Fn bit_alloc "size_t nbits" +.Ft void +.Fn bit_decl "bitstr_t *name" "size_t nbits" +.Ft void +.Fn bit_clear "bitstr_t *name" "size_t bit" +.Ft void +.Fn bit_count "bitstr_t *name" "size_t count" "size_t nbits" "ssize_t *value" +.Ft void +.Fn bit_ffc "bitstr_t *name" "size_t nbits" "ssize_t *value" +.Ft void +.Fn bit_ffs "bitstr_t *name" "size_t nbits" "ssize_t *value" +.Ft void +.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" "size_t start" "size_t nbits" "ssize_t *value" +.Ft void +.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" "size_t nbits" "size_t size" "ssize_t *value" +.Ft void +.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" "size_t start" "size_t nbits" "size_t size" "ssize_t *value" +.Ft void +.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" "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" "size_t start" "size_t stop" +.Ft void +.Fn bit_nset "bitstr_t *name" "size_t start" "size_t stop" +.Ft int +.Fn bit_ntest "bitstr_t *name" "size_t start" "size_t stop" "int match" +.Ft void +.Fn bit_set "bitstr_t *name" "size_t bit" +.Ft int +.Fn bitstr_size "size_t nbits" +.Ft int +.Fn bit_test "bitstr_t *name" "size_t bit" +.Sh DESCRIPTION +These macros operate on strings of bits. +.Pp +The function +.Fn bit_alloc +returns a pointer of type +.Dq Fa "bitstr_t *" +to sufficient space to store +.Fa nbits +bits, or +.Dv NULL +if no space is available. +If successful, the returned bit string is initialized with all bits cleared. +.Pp +The macro +.Fn bit_decl +declares a bit string with sufficient space to store +.Fa nbits +bits. +.Fn bit_decl +may be used to include statically sized bit strings in structure +definitions or to create bit strings on the stack. +Users of this macro are responsible for initialization of the bit string, +typically via a global initialization of the containing struct or use of the +.Fn bit_nset +or +.Fn bin_nclear +functions. +.Pp +The macro +.Fn bitstr_size +returns the number of bytes necessary to store +.Fa nbits +bits. +This is useful for copying bit strings. +.Pp +The functions +.Fn bit_clear +and +.Fn bit_set +clear or set the zero-based numbered bit +.Fa bit , +in the bit string +.Ar name . +.Pp +The +.Fn bit_nset +and +.Fn bit_nclear +functions +set or clear the zero-based numbered bits from +.Fa start +through +.Fa stop +in the bit string +.Ar name . +.Pp +The +.Fn bit_test +function +evaluates to non-zero if the zero-based numbered bit +.Fa bit +of bit string +.Fa name +is set, and zero otherwise. +.Pp +The +.Fn bit_ntest +function +evaluates to non-zero if the zero-based numbered bits from +.Fa start +through +.Fa stop +in the bit string +.Ar name +all have the value +.Ar match . +.Pp +The function +.Fn bit_ffc +stores in the location referenced by +.Fa value +the zero-based number of the first bit not set in the array of +.Fa nbits +bits referenced by +.Fa name . +If all bits are set, the location referenced by +.Fa value +is set to \-1. +.Pp +The +.Fn bit_ffs +function +stores in the location referenced by +.Fa value +the zero-based number of the first bit set in the array of +.Fa nbits +bits referenced by +.Fa name . +If no bits are set, the location referenced by +.Fa value +is set to \-1. +.Pp +The function +.Fn bit_ffc_at +stores in the location referenced by +.Fa value +the zero-based number of the first bit not set in the array of +.Fa nbits +bits referenced by +.Fa name , +at or after the zero-based bit index +.Fa start . +If all bits at or after +.Fa start +are set, the location referenced by +.Fa value +is set to \-1. +.Pp +The +.Fn bit_ffs_at +function +stores in the location referenced by +.Fa value +the zero-based number of the first bit set in the array of +.Fa nbits +bits referenced by +.Fa name , +at or after the zero-based bit index +.Fa start . +If no bits are set after +.Fa start , +the location referenced by +.Fa value +is set to \-1. +.Pp +The +.Fn bit_ff_at +function +stores in the location referenced by +.Fa value +the zero-based number of the first bit in the array of +.Fa nbits +bits referenced by +.Fa name , +at or after the zero-based bit index +.Fa start +that has value +.Fa match . +If no bits after +.Fa start +match that value, the location referenced by +.Fa value +is set to \-1. +.Pp +The +.Fn bit_ffc_area +function stores in the location referenced by +.Fa value +the zero-based number of the first bit beginning a sequence of unset bits of +at least +.Fa size +unset bits in the array of +.Fa nbits +bits referenced by +.Fa name . +If no sequence of contiguous unset bits of the specified +.Fa size +can be found, the location referenced by +.Fa value +is set to \-1. +.Pp +The +.Fn bit_ffs_area +function stores in the location referenced by +.Fa value +the zero-based number of the first bit beginning a sequence of set bits of +at least +.Fa size +set bits in the array of +.Fa nbits +bits referenced by +.Fa name . +If no sequence of contiguous set bits of the specified +.Fa size +can be found, the location referenced by +.Fa value +is set to \-1. +.Pp +The +.Fn bit_ffc_area_at +function stores in the location referenced by +.Fa value +the zero-based number of the first bit beginning a sequence of unset bits of +at least +.Fa size +unset bits in the array of +.Fa nbits +bits referenced by +.Fa name , +at or after the zero-based bit index +.Fa start . +If no sequence of contiguous unset bits of the specified +.Fa size +can be found at or after +.Fa start , +the location referenced by +.Fa value +is set to \-1. +.Pp +The +.Fn bit_ffs_area_at +function stores in the location referenced by +.Fa value +the zero-based number of the first bit beginning a sequence of set bits of +at least +.Fa size +set bits in the array of +.Fa nbits +bits referenced by +.Fa name , +at or after the zero-based bit index +.Fa start . +If no sequence of contiguous set bits of the specified +.Fa size +can be found at or after +.Fa start , +the location referenced by +.Fa value +is set to \-1. +.Pp +The +.Fn bit_ff_area_at +function stores in the location referenced by +.Fa value +the zero-based number of the first bit beginning a sequence of bits of +at least +.Fa size +bits in the array of +.Fa nbits +bits referenced by +.Fa name , +at or after the zero-based bit index +.Fa start +in which all bits have the value +.Fa match . +If no sequence of contiguous such bits of the specified +.Fa size +can be found at or after +.Fa start , +the location referenced by +.Fa value +is set to \-1. +.Pp +The +.Fn bit_count +function stores in the location referenced by +.Fa value +the number of bits set in the array of +.Fa nbits +bits referenced by +.Fa name , +at or after the zero-based bit index +.Fa start . +.Pp +The macro +.Fn bit_foreach +traverses all set bits in the array of +.Fa nbits +referenced by +.Fa name +in the forward direction, assigning each location in turn to +.Fa var . +.Pp +The macro +.Fn bit_foreach_at +traverses all set bits in the array of +.Fa nbits +referenced by +.Fa name +in the forward direction at or after the zero-based bit index +.Fa start , +assigning each location in turn to +.Fa var . +.Pp +The macro +.Fn bit_foreach_unset +traverses all unset bits in the array of +.Fa nbits +referenced by +.Fa name +in the forward direction, assigning each location in turn to +.Fa var . +.Pp +The macro +.Fn bit_foreach_unset_at +traverses all unset bits in the array of +.Fa nbits +referenced by +.Fa name +in the forward direction at or after the zero-based bit index +.Fa start , +assigning each location in turn to +.Fa var . +.Pp +The arguments in bit string macros are evaluated only once and may safely +have side effects. +.Sh EXAMPLES +.Bd -literal -offset indent +#include <limits.h> +#include <bitstring.h> + +\&... +#define LPR_BUSY_BIT 0 +#define LPR_FORMAT_BIT 1 +#define LPR_DOWNLOAD_BIT 2 +\&... +#define LPR_AVAILABLE_BIT 9 +#define LPR_MAX_BITS 10 + +make_lpr_available() +{ + bitstr_t bit_decl(bitlist, LPR_MAX_BITS); + ... + bit_nclear(bitlist, 0, LPR_MAX_BITS - 1); + ... + if (!bit_test(bitlist, LPR_BUSY_BIT)) { + bit_clear(bitlist, LPR_FORMAT_BIT); + bit_clear(bitlist, LPR_DOWNLOAD_BIT); + bit_set(bitlist, LPR_AVAILABLE_BIT); + } +} +.Ed +.Sh SEE ALSO +.Xr malloc 3 , +.Xr stdbit 3 , +.Xr bitset 9 +.Sh HISTORY +The +.Nm bitstring +functions first appeared in +.Bx 4.4 . diff --git a/static/freebsd/man3/end.3 b/static/freebsd/man3/end.3 new file mode 100644 index 00000000..53800342 --- /dev/null +++ b/static/freebsd/man3/end.3 @@ -0,0 +1,76 @@ +.\" Copyright (c) 1986 +.\" 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 August 28, 2000 +.Dt END 3 +.Os +.Sh NAME +.Nm end , +.Nm etext , +.Nm edata +.Nd end boundaries of image segments +.Sh SYNOPSIS +.Vt extern end ; +.Vt extern etext ; +.Vt extern edata ; +.Sh DESCRIPTION +The globals +.Va end , etext +and +.Va edata +are program segment end addresses. +.Pp +.Va etext +is the first address after the end of the text segment. +.Pp +.Va edata +is the first address after the end of the initialized data segment. +.Pp +.Va end +is the first address after the end of the data segment +.Pq Tn BSS +when the program is loaded. +Use the +.Xr sbrk 2 +.\".Fn sbrk 0 +system call with zero as its argument to find the current end of the +data segment. +.Sh SEE ALSO +.Xr sbrk 2 , +.Xr malloc 3 , +.Xr a.out 5 +.Sh HISTORY +An +.Nm +manual page appeared in +.At v6 . +.Sh BUGS +Traditionally, no variable existed that pointed to the start of the +text segment because the text segment always started at address zero. +Although it is no longer valid to make this assumption, no +variable similar to the ones documented above exists to point to the +start of the text segment. diff --git a/static/freebsd/man3/fpgetround.3 b/static/freebsd/man3/fpgetround.3 new file mode 100644 index 00000000..c827122e --- /dev/null +++ b/static/freebsd/man3/fpgetround.3 @@ -0,0 +1,173 @@ +.\" Copyright (c) 1993 Andrew Moore, Talke Studio +.\" 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 December 3, 2010 +.Dt FPGETROUND 3 +.Os +.Sh NAME +.Nm fpgetround , +.Nm fpsetround , +.Nm fpsetprec , +.Nm fpgetprec , +.Nm fpgetmask , +.Nm fpsetmask , +.Nm fpgetsticky , +.Nm fpresetsticky +.Nd IEEE floating point interface +.Sh SYNOPSIS +.In ieeefp.h +.Bd -literal +typedef enum { + FP_RN, /* round to nearest */ + FP_RM, /* round down to minus infinity */ + FP_RP, /* round up to plus infinity */ + FP_RZ /* truncate */ +} fp_rnd_t; +.Ed +.Ft fp_rnd_t +.Fn fpgetround void +.Ft fp_rnd_t +.Fn fpsetround "fp_rnd_t direction" +.Bd -literal +typedef enum { + FP_PS, /* 24 bit (single-precision) */ + FP_PRS, /* reserved */ + FP_PD, /* 53 bit (double-precision) */ + FP_PE /* 64 bit (extended-precision) */ +} fp_prec_t; +.Ed +.Ft fp_prec_t +.Fn fpgetprec void +.Ft fp_prec_t +.Fn fpsetprec "fp_prec_t precision" +.Bd -literal +#define fp_except_t int +#define FP_X_INV 0x01 /* invalid operation */ +#define FP_X_DNML 0x02 /* denormal */ +#define FP_X_DZ 0x04 /* zero divide */ +#define FP_X_OFL 0x08 /* overflow */ +#define FP_X_UFL 0x10 /* underflow */ +#define FP_X_IMP 0x20 /* (im)precision */ +#define FP_X_STK 0x40 /* stack fault */ +.Ed +.Ft fp_except_t +.Fn fpgetmask void +.Ft fp_except_t +.Fn fpsetmask "fp_except_t mask" +.Ft fp_except_t +.Fn fpgetsticky void +.Ft fp_except_t +.Fn fpresetsticky "fp_except_t sticky" +.Sh DESCRIPTION +The routines described herein are deprecated. +New code should use the functionality provided by +.Xr fenv 3 . +.Pp +When a floating point exception is detected, the exception sticky flag is +set and the exception mask is tested. +If the mask is set, then a trap +occurs. +These routines allow both setting the floating point exception +masks, and resetting the exception sticky flags after an exception is +detected. +In addition, they allow setting the floating point rounding mode +and precision. +.Pp +The +.Fn fpgetround +function +returns the current floating point rounding mode. +.Pp +The +.Fn fpsetround +function +sets the floating point rounding mode and returns +the previous mode. +.Pp +The +.Fn fpgetprec +function +returns the current floating point precision. +.Pp +The +.Fn fpsetprec +function +sets the floating point precision and returns +the previous precision. +.Pp +The +.Fn fpgetmask +function +returns the current floating point exception masks. +.Pp +The +.Fn fpsetmask +function +sets the floating point exception masks and returns the +previous masks. +.Pp +The +.Fn fpgetsticky +function +returns the current floating point sticky flags. +.Pp +The +.Fn fpresetsticky +function +clears the floating point sticky flags and returns +the previous flags. +.Pp +Sample code which prevents a trap on divide-by-zero: +.Bd -literal -offset indent +fpsetmask(~FP_X_DZ); +a = 1.0; +b = 0; +c = a / b; +fpresetsticky(FP_X_DZ); +fpsetmask(FP_X_DZ); +.Ed +.Sh IMPLEMENTATION NOTES +The +.Fn fpgetprec +and +.Fn fpsetprec +functions provide functionality unavailable on many platforms. +At present, they are implemented only on the i386 and amd64 platforms. +Changing precision is not a supported feature: +it may be ineffective when code is compiled to take advantage of SSE, +and many library functions and compiler optimizations depend upon the +default precision for correct behavior. +.Sh SEE ALSO +.Xr fenv 3 , +.Xr isnan 3 +.Sh HISTORY +These routines are based on SysV/386 routines of the same name. +.Sh CAVEATS +After a floating point exception and before a mask is set, the sticky +flags must be reset. +If another exception occurs before the sticky +flags are reset, then a wrong exception type may be signaled. diff --git a/static/freebsd/man3/intro.3 b/static/freebsd/man3/intro.3 new file mode 100644 index 00000000..952183d7 --- /dev/null +++ b/static/freebsd/man3/intro.3 @@ -0,0 +1,384 @@ +.\" 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 November 10, 2025 +.Dt INTRO 3 +.Os +.Sh NAME +.Nm intro +.Nd introduction to the C libraries +.Sh SYNOPSIS +.Nm cc +.Op Ar flags +.Ar +.Op Fl llibrary +.Sh DESCRIPTION +This section provides an overview of the C +library functions, their error returns and other +common definitions and concepts. +Most of these functions are available from the C library, +.Em libc . +Other libraries, such as the math library, +.Em libm , +must be indicated at compile time with the +.Fl l +option of the compiler. +.Pp +The various libraries (followed by the loader flag): +.Bl -tag -width "libbluetooth" +.It Em libbluetooth +.Pq Fl l Ns Ar bluetooth +The bluetooth library. +See +.Xr bluetooth 3 . +.It Em libc +.Pq Fl l Ns Ar c +Standard C library functions. +When using the C compiler +.Xr cc 1 , +it is not necessary +to supply the loader flag +.Fl l Ns Ar c +for these functions. +There are several `libraries' or groups of functions included inside of +.Em libc : +.Bl -tag -width "XXXXXX" +.It standard I/O routines +see +.Xr stdio 3 +.It database routines +see +.Xr db 3 +.It bit string operators +see +.Xr bitstring 3 +.It bit and byte utilities +see +.Xr stdbit 3 +.It string operators +see +.Xr string 3 +and +.Xr bstring 3 +.It character tests and character operators +see +.Xr ctype 3 +.It storage allocation +see +.Xr mpool 3 +.It regular-expressions +see +.Xr regex 3 +.It remote procedure calls (RPC) +see +.Xr rpc 3 +.It time functions +see +.Xr time 3 +.It signal handling +see +.Xr signal 3 +.El +.It Em libcalendar +.Pq Fl l Ns Ar calendar +The calendar arithmetic library. +See +.Xr calendar 3 . +.It Em libcam +.Pq Fl l Ns Ar cam +The common access method user library. +See +.Xr cam 3 . +.It Em libcrypt +.Pq Fl l Ns Ar crypt +The crypt library. +See +.Xr crypt 3 . +.It Em libcurses +.Pq Fl l Ns Ar curses Fl l Ns Ar termcap +Terminal independent screen management routines +for two dimensional non-bitmap display terminals. +See +.Xr ncurses 3 . +.It Em libcuse +.Pq Fl l Ns Ar cuse +The userland character device library. +See +.Xr cuse 3 . +.It Em libcompat +.Pq Fl l Ns Ar compat +Functions which are obsolete but are available for compatibility with +.Bx 4.3 . +In particular, +a number of system call interfaces provided in previous releases of +.Bx +have been included for source code compatibility. +Use of these routines should, for the most part, be avoided. +The manual page entry for each compatibility routine +indicates the proper interface to use. +.It Em libdevinfo +.Pq Fl l Ns Ar devinfo +The Device and Resource Information Utility library. +See +.Xr devinfo 3 . +.It Em libdevstat +.Pq Fl l Ns Ar devstat +The Device Statistics library. +See +.Xr devstat 3 . +.It Em libdwarf +.Pq Fl l Ns Ar dwarf +The DWARF access library. +See +.Xr dwarf 3 . +.It Em libelf +.Pq Fl l Ns Ar elf +The ELF access library. +See +.Xr elf 3 . +.It Em libfetch +.Pq Fl l Ns Ar fetch +The file transfer library. +See +.Xr fetch 3 . +.It Em libfigpar +.Pq Fl l Ns Ar figpar +The configuration file parsing library. +See +.Xr figpar 3 . +.It Em libgpio +.Pq Fl l Ns Ar gpio +The general-purpose input output library (GPIO). +See +.Xr gpio 3 . +.It Em libgssapi +.Pq Fl l Ns Ar gssapi +The generic security service application programming +interface. +See +.Xr gssapi 3 . +.It Em libjail +.Pq Fl l Ns Ar jail +The jail library. +See +.Xr jail 3 . +.It Em libkvm +.Pq Fl l Ns Ar kvm +Functions used to access kernel memory are in this library. +They can be used +against both a running system and a crash dump. +See +.Xr kvm 3 . +.It Em libl +.Pq Fl l Ns Ar l +The library for +.Xr lex 1 . +.It Em libm +.Pq Fl l Ns Ar m +The math library. +See +.Xr math 3 . +.It Em libmd +.Pq Fl l Ns Ar md +The message digest library. +See +.Xr md4 3 , +.Xr md5 3 , +.Xr sha 3 , +.Xr sha256 3 , +.Xr sha512 3 , +.Xr ripemd 3 , +.Xr skein 3 . +.It Em libmp +.Pq Fl l Ns Ar mp +.It Em libpam +.Pq Fl l Ns Ar pam +The pluggable authentication module library. +See +.Xr pam 3 . +.It Em libpcap +.Pq Fl l Ns Ar pcap +The packet capture library. +See +.Xr pcap 3 . +.It Em libpmc +.Pq Fl l Ns Ar pmc +The performance counters library. +See +.Xr pmc 3 . +.It Em libpthread +.Pq Fl l Ns Ar pthread +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. +See +.Xr sysdecode 3 . +.It Em libtermcap +.Pq Fl l Ns Ar termcap +The terminal independent operation library package. +See +.Xr termcap 3 . +.It Em libusb +.Pq Fl l Ns Ar usb +The USB access library. +See +.Xr usb 3 . +.It Em libvgl +.Pq Fl l Ns Ar vgl +The video graphics library. +See +.Xr vgl 3 . +.It Em liby +.Pq Fl l Ns Ar y +The library for +.Xr yacc 1 . +.It Em libz +.Pq Fl l Ns Ar z +The general-purpose data compression library. +See +.Xr zlib 3 . +.El +.Sh FILES +.Bl -tag -width /usr/lib/libm_p.a -compact +.It Pa /usr/lib/libc.a +the C library +.It Pa /usr/lib/libm.a +the math library +.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 make.conf 5 , +.Xr src.conf 5 +.Sh HISTORY +An +.Nm +manual appeared in +.At v7 . diff --git a/static/freebsd/man3/makedev.3 b/static/freebsd/man3/makedev.3 new file mode 100644 index 00000000..3c0e176a --- /dev/null +++ b/static/freebsd/man3/makedev.3 @@ -0,0 +1,100 @@ +.\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 3, 2017 +.Dt MAKEDEV 3 +.Os +.Sh NAME +.Nm makedev , +.Nm major , +.Nm minor +.Nd device number conversion +.Sh SYNOPSIS +.In sys/types.h +.Ft dev_t +.Fn makedev "int major" "int minor" +.Ft int +.Fn major "dev_t dev" +.Ft int +.Fn minor "dev_t dev" +.Sh DESCRIPTION +The +.Fn makedev +macro returns a device number created from the provided +.Fa major +and +.Fa minor +number. +The +.Fn major +and +.Fn minor +macros return the original numbers from the device number +.Fa dev . +In other words, for a value +.Va dev +of the type +.Vt dev_t , +and values +.Va ma , mi +of the type +.Vt int , +the assertions +.Dl dev == makedev(major(dev), minor(dev)) +.Dl ma == major(makedev(ma, mi)) +.Dl mi == minor(makedev(ma, mi)) +are valid. +.Pp +In previous implementations of +.Fx +all block and character devices were uniquely identified by a pair of +stable major and minor numbers. +The major number referred to a certain device class (e.g. disks, TTYs) +while the minor number identified an instance within the device class. +Later versions of +.Fx +automatically generate a unique device number for each character device +visible in +.Pa /dev/ . +These numbers are not divided in device classes and are not guaranteed +to be stable upon reboot or driver reload. +.Pp +On +.Fx +these macros are only used by utilities that need to exchange numbers +with other operating systems that may use different encodings for +.Vt dev_t , +but also applications that present these numbers to the user in a more +conventional way. +.Sh RETURN VALUES +The +.Fn major +and +.Fn minor +macros return numbers whose value can span the complete range of an +.Vt int . +.Sh SEE ALSO +.Xr mknod 2 , +.Xr devname 3 , +.Xr devfs 4 diff --git a/static/freebsd/man3/offsetof.3 b/static/freebsd/man3/offsetof.3 new file mode 100644 index 00000000..f757d58a --- /dev/null +++ b/static/freebsd/man3/offsetof.3 @@ -0,0 +1,45 @@ +.\" $OpenBSD: offsetof.3,v 1.2 2010/02/18 18:30:19 jmc Exp $ +.\" +.\" Copyright (c) 2010 Thomas Pfaff <tpfaff@tp76.info> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd February 18, 2010 +.Dt OFFSETOF 3 +.Os +.Sh NAME +.Nm offsetof +.Nd offset of a structure member +.Sh SYNOPSIS +.In stddef.h +.Ft size_t +.Fn offsetof "type" "member" +.Sh DESCRIPTION +The +.Fn offsetof +macro expands to an integer constant expression of type +.Ft size_t +and yields the offset, +in bytes, of the field +.Ar member +from the start of the structure +.Ar type . +.Pp +A compiler error will result if +.Ar member +is not aligned to a byte boundary (i.e. it is a bit-field). +.Sh STANDARDS +The +.Fn offsetof +macro conforms to +.St -ansiC . diff --git a/static/freebsd/man3/pthread.3 b/static/freebsd/man3/pthread.3 new file mode 100644 index 00000000..1cb13981 --- /dev/null +++ b/static/freebsd/man3/pthread.3 @@ -0,0 +1,552 @@ +.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 October 12, 2021 +.Dt PTHREAD 3 +.Os +.Sh NAME +.Nm pthread +.Nd POSIX thread functions +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Sh DESCRIPTION +POSIX threads are a set of functions that support applications with +requirements for multiple flows of control, called +.Em threads , +within a process. +Multithreading is used to improve the performance of a +program. +.Pp +The POSIX thread functions are summarized in this section in the following +groups: +.Pp +.Bl -bullet -offset indent -compact +.It +Thread Routines +.It +Attribute Object Routines +.It +Mutex Routines +.It +Condition Variable Routines +.It +Read/Write Lock Routines +.It +Per-Thread Context Routines +.It +Cleanup Routines +.El +.Pp +.Fx +extensions to the POSIX thread functions are summarized in +.Xr pthread_np 3 . +.Ss Thread Routines +.Bl -tag -width indent +.It Xo +.Ft int +.Fo pthread_create +.Fa "pthread_t *thread" "const pthread_attr_t *attr" +.Fa "void *\*[lp]*start_routine\*[rp]\*[lp]void *\*[rp]" "void *arg" +.Fc +.Xc +Creates a new thread of execution. +.It Xo +.Ft int +.Fn pthread_cancel "pthread_t thread" +.Xc +Cancels execution of a thread. +.It Xo +.Ft int +.Fn pthread_detach "pthread_t thread" +.Xc +Marks a thread for deletion. +.It Xo +.Ft int +.Fn pthread_equal "pthread_t t1" "pthread_t t2" +.Xc +Compares two thread IDs. +.It Xo +.Ft void +.Fn pthread_exit "void *value_ptr" +.Xc +Terminates the calling thread. +.It Xo +.Ft int +.Fn pthread_join "pthread_t thread" "void **value_ptr" +.Xc +Causes the calling thread to wait for the termination of the specified thread. +.It Xo +.Ft int +.Fn pthread_kill "pthread_t thread" "int sig" +.Xc +Delivers a signal to a specified thread. +.It Xo +.Ft int +.Fn pthread_once "pthread_once_t *once_control" "void \*[lp]*init_routine\*[rp]\*[lp]void\*[rp]" +.Xc +Calls an initialization routine once. +.It Xo +.Ft pthread_t +.Fn pthread_self void +.Xc +Returns the thread ID of the calling thread. +.It Xo +.Ft int +.Fn pthread_setcancelstate "int state" "int *oldstate" +.Xc +Sets the current thread's cancelability state. +.It Xo +.Ft int +.Fn pthread_setcanceltype "int type" "int *oldtype" +.Xc +Sets the current thread's cancelability type. +.It Xo +.Ft void +.Fn pthread_testcancel void +.Xc +Creates a cancellation point in the calling thread. +.It Xo +.Ft void +.Fn pthread_yield void +.Xc +Allows the scheduler to run another thread instead of the current one. +.El +.Ss Attribute Object Routines +.Bl -tag -width indent +.It Xo +.Ft int +.Fn pthread_attr_destroy "pthread_attr_t *attr" +.Xc +Destroy a thread attributes object. +.It Xo +.Ft int +.Fo pthread_attr_getinheritsched +.Fa "const pthread_attr_t *attr" "int *inheritsched" +.Fc +.Xc +Get the inherit scheduling attribute from a thread attributes object. +.It Xo +.Ft int +.Fo pthread_attr_getschedparam +.Fa "const pthread_attr_t *attr" "struct sched_param *param" +.Fc +.Xc +Get the scheduling parameter attribute from a thread attributes object. +.It Xo +.Ft int +.Fn pthread_attr_getschedpolicy "const pthread_attr_t *attr" "int *policy" +.Xc +Get the scheduling policy attribute from a thread attributes object. +.It Xo +.Ft int +.Fn pthread_attr_getscope "const pthread_attr_t *attr" "int *contentionscope" +.Xc +Get the contention scope attribute from a thread attributes object. +.It Xo +.Ft int +.Fn pthread_attr_getstacksize "const pthread_attr_t *attr" "size_t *stacksize" +.Xc +Get the stack size attribute from a thread attributes object. +.It Xo +.Ft int +.Fn pthread_attr_getstackaddr "const pthread_attr_t *attr" "void **stackaddr" +.Xc +Get the stack address attribute from a thread attributes object. +.It Xo +.Ft int +.Fn pthread_attr_getdetachstate "const pthread_attr_t *attr" "int *detachstate" +.Xc +Get the detach state attribute from a thread attributes object. +.It Xo +.Ft int +.Fn pthread_attr_init "pthread_attr_t *attr" +.Xc +Initialize a thread attributes object with default values. +.It Xo +.Ft int +.Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched" +.Xc +Set the inherit scheduling attribute in a thread attributes object. +.It Xo +.Ft int +.Fo pthread_attr_setschedparam +.Fa "pthread_attr_t *attr" "const struct sched_param *param" +.Fc +.Xc +Set the scheduling parameter attribute in a thread attributes object. +.It Xo +.Ft int +.Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy" +.Xc +Set the scheduling policy attribute in a thread attributes object. +.It Xo +.Ft int +.Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope" +.Xc +Set the contention scope attribute in a thread attributes object. +.It Xo +.Ft int +.Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize" +.Xc +Set the stack size attribute in a thread attributes object. +.It Xo +.Ft int +.Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr" +.Xc +Set the stack address attribute in a thread attributes object. +.It Xo +.Ft int +.Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate" +.Xc +Set the detach state in a thread attributes object. +.El +.Ss Mutex Routines +.Bl -tag -width indent +.It Xo +.Ft int +.Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr" +.Xc +Destroy a mutex attributes object. +.It Xo +.Ft int +.Fn pthread_mutexattr_getprioceiling "const pthread_mutexattr_t *restrict attr" "int *restrict ceiling" +.Xc +Obtain priority ceiling attribute of mutex attribute object. +.It Xo +.Ft int +.Fn pthread_mutexattr_getprotocol "const pthread_mutexattr_t *restrict attr" "int *restrict protocol" +.Xc +Obtain protocol attribute of mutex attribute object. +.It Xo +.Ft int +.Fn pthread_mutexattr_gettype "const pthread_mutexattr_t *restrict attr" "int *restrict type" +.Xc +Obtain the mutex type attribute in the specified mutex attributes object. +.It Xo +.Ft int +.Fn pthread_mutexattr_init "pthread_mutexattr_t *attr" +.Xc +Initialize a mutex attributes object with default values. +.It Xo +.Ft int +.Fn pthread_mutexattr_setprioceiling "pthread_mutexattr_t *attr" "int ceiling" +.Xc +Set priority ceiling attribute of mutex attribute object. +.It Xo +.Ft int +.Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol" +.Xc +Set protocol attribute of mutex attribute object. +.It Xo +.Ft int +.Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type" +.Xc +Set the mutex type attribute that is used when a mutex is created. +.It Xo +.Ft int +.Fn pthread_mutex_destroy "pthread_mutex_t *mutex" +.Xc +Destroy a mutex. +.It Xo +.Ft int +.Fo pthread_mutex_init +.Fa "pthread_mutex_t *mutex" "const pthread_mutexattr_t *attr" +.Fc +.Xc +Initialize a mutex with specified attributes. +.It Xo +.Ft int +.Fn pthread_mutex_lock "pthread_mutex_t *mutex" +.Xc +Lock a mutex and block until it becomes available. +.It Xo +.Ft int +.Fo pthread_mutex_timedlock +.Fa "pthread_mutex_t *mutex" "const struct timespec *abstime" +.Fc +.Xc +Lock a mutex and block until it becomes available or until the timeout expires. +.It Xo +.Ft int +.Fn pthread_mutex_trylock "pthread_mutex_t *mutex" +.Xc +Try to lock a mutex, but do not block if the mutex is locked by another thread, +including the current thread. +.It Xo +.Ft int +.Fn pthread_mutex_unlock "pthread_mutex_t *mutex" +.Xc +Unlock a mutex. +.El +.Ss Condition Variable Routines +.Bl -tag -width indent +.It Xo +.Ft int +.Fn pthread_condattr_destroy "pthread_condattr_t *attr" +.Xc +Destroy a condition variable attributes object. +.It Xo +.Ft int +.Fn pthread_condattr_init "pthread_condattr_t *attr" +.Xc +Initialize a condition variable attributes object with default values. +.It Xo +.Ft int +.Fn pthread_cond_broadcast "pthread_cond_t *cond" +.Xc +Unblock all threads currently blocked on the specified condition variable. +.It Xo +.Ft int +.Fn pthread_cond_destroy "pthread_cond_t *cond" +.Xc +Destroy a condition variable. +.It Xo +.Ft int +.Fn pthread_cond_init "pthread_cond_t *cond" "const pthread_condattr_t *attr" +.Xc +Initialize a condition variable with specified attributes. +.It Xo +.Ft int +.Fn pthread_cond_signal "pthread_cond_t *cond" +.Xc +Unblock at least one of the threads blocked on the specified condition variable. +.It Xo +.Ft int +.Fo pthread_cond_timedwait +.Fa "pthread_cond_t *cond" "pthread_mutex_t *mutex" +.Fa "const struct timespec *abstime" +.Fc +.Xc +Unlock the specified mutex, wait no longer than the specified time for +a condition, and then relock the mutex. +.It Xo +.Ft int +.Fn pthread_cond_wait "pthread_cond_t *" "pthread_mutex_t *mutex" +.Xc +Unlock the specified mutex, wait for a condition, and relock the mutex. +.El +.Ss Read/Write Lock Routines +.Bl -tag -width indent +.It Xo +.Ft int +.Fn pthread_rwlock_destroy "pthread_rwlock_t *lock" +.Xc +Destroy a read/write lock object. +.It Xo +.Ft int +.Fo pthread_rwlock_init +.Fa "pthread_rwlock_t *lock" "const pthread_rwlockattr_t *attr" +.Fc +.Xc +Initialize a read/write lock object. +.It Xo +.Ft int +.Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock" +.Xc +Lock a read/write lock for reading, blocking until the lock can be +acquired. +.It Xo +.Ft int +.Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock" +.Xc +Attempt to lock a read/write lock for reading, without blocking if the +lock is unavailable. +.It Xo +.Ft int +.Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock" +.Xc +Attempt to lock a read/write lock for writing, without blocking if the +lock is unavailable. +.It Xo +.Ft int +.Fn pthread_rwlock_unlock "pthread_rwlock_t *lock" +.Xc +Unlock a read/write lock. +.It Xo +.Ft int +.Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock" +.Xc +Lock a read/write lock for writing, blocking until the lock can be +acquired. +.It Xo +.Ft int +.Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr" +.Xc +Destroy a read/write lock attribute object. +.It Xo +.Ft int +.Fo pthread_rwlockattr_getpshared +.Fa "const pthread_rwlockattr_t *attr" "int *pshared" +.Fc +.Xc +Retrieve the process shared setting for the read/write lock attribute +object. +.It Xo +.Ft int +.Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr" +.Xc +Initialize a read/write lock attribute object. +.It Xo +.Ft int +.Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int pshared" +.Xc +Set the process shared setting for the read/write lock attribute object. +.El +.Ss Per-Thread Context Routines +.Bl -tag -width indent +.It Xo +.Ft int +.Fn pthread_key_create "pthread_key_t *key" "void \*[lp]*routine\*[rp]\*[lp]void *\*[rp]" +.Xc +Create a thread-specific data key. +.It Xo +.Ft int +.Fn pthread_key_delete "pthread_key_t key" +.Xc +Delete a thread-specific data key. +.It Xo +.Ft "void *" +.Fn pthread_getspecific "pthread_key_t key" +.Xc +Get the thread-specific value for the specified key. +.It Xo +.Ft int +.Fn pthread_setspecific "pthread_key_t key" "const void *value_ptr" +.Xc +Set the thread-specific value for the specified key. +.El +.Ss Cleanup Routines +.Bl -tag -width indent +.It Xo +.Ft int +.Fo pthread_atfork +.Fa "void \*[lp]*prepare\*[rp]\*[lp]void\*[rp]" +.Fa "void \*[lp]*parent\*[rp]\*[lp]void\*[rp]" +.Fa "void \*[lp]*child\*[rp]\*[lp]void\*[rp]" +.Fc +.Xc +Register fork handlers. +.It Xo +.Ft void +.Fn pthread_cleanup_pop "int execute" +.Xc +Remove the routine at the top of the calling thread's cancellation cleanup +stack and optionally invoke it. +.It Xo +.Ft void +.Fn pthread_cleanup_push "void \*[lp]*routine\*[rp]\*[lp]void *\*[rp]" "void *routine_arg" +.Xc +Push the specified cancellation cleanup handler onto the calling thread's +cancellation stack. +.El +.Sh IMPLEMENTATION NOTES +The current +.Fx +POSIX thread implementation is built into the +.Lb libthr +library. +It contains thread-safe versions of +.Lb libc +functions and the thread functions. +Threaded applications are linked with this library. +.Sh SEE ALSO +.Xr libthr 3 , +.Xr pthread_atfork 3 , +.Xr pthread_attr 3 , +.Xr pthread_cancel 3 , +.Xr pthread_cleanup_pop 3 , +.Xr pthread_cleanup_push 3 , +.Xr pthread_cond_broadcast 3 , +.Xr pthread_cond_destroy 3 , +.Xr pthread_cond_init 3 , +.Xr pthread_cond_signal 3 , +.Xr pthread_cond_timedwait 3 , +.Xr pthread_cond_wait 3 , +.Xr pthread_condattr_destroy 3 , +.Xr pthread_condattr_init 3 , +.Xr pthread_create 3 , +.Xr pthread_detach 3 , +.Xr pthread_equal 3 , +.Xr pthread_exit 3 , +.Xr pthread_getspecific 3 , +.Xr pthread_join 3 , +.Xr pthread_key_delete 3 , +.Xr pthread_kill 3 , +.Xr pthread_mutex_destroy 3 , +.Xr pthread_mutex_init 3 , +.Xr pthread_mutex_lock 3 , +.Xr pthread_mutex_trylock 3 , +.Xr pthread_mutex_unlock 3 , +.Xr pthread_mutexattr_destroy 3 , +.Xr pthread_mutexattr_getprioceiling 3 , +.Xr pthread_mutexattr_getprotocol 3 , +.Xr pthread_mutexattr_gettype 3 , +.Xr pthread_mutexattr_init 3 , +.Xr pthread_mutexattr_setprioceiling 3 , +.Xr pthread_mutexattr_setprotocol 3 , +.Xr pthread_mutexattr_settype 3 , +.Xr pthread_np 3 , +.Xr pthread_once 3 , +.Xr pthread_rwlock_destroy 3 , +.Xr pthread_rwlock_init 3 , +.Xr pthread_rwlock_rdlock 3 , +.Xr pthread_rwlock_unlock 3 , +.Xr pthread_rwlock_wrlock 3 , +.Xr pthread_rwlockattr_destroy 3 , +.Xr pthread_rwlockattr_getpshared 3 , +.Xr pthread_rwlockattr_init 3 , +.Xr pthread_rwlockattr_setpshared 3 , +.Xr pthread_self 3 , +.Xr pthread_setcancelstate 3 , +.Xr pthread_setcanceltype 3 , +.Xr pthread_setspecific 3 , +.Xr pthread_testcancel 3 +.Sh STANDARDS +The functions with the +.Nm pthread_ +prefix and not +.Nm _np +suffix or +.Nm pthread_rwlock +prefix conform to +.St -p1003.1-96 . +.Pp +The functions with the +.Nm pthread_ +prefix and +.Nm _np +suffix are non-portable extensions to POSIX threads. +.Pp +The functions with the +.Nm pthread_rwlock +prefix are extensions created by The Open Group as part of the +.St -susv2 . diff --git a/static/freebsd/man3/pthread_affinity_np.3 b/static/freebsd/man3/pthread_affinity_np.3 new file mode 100644 index 00000000..86c43d22 --- /dev/null +++ b/static/freebsd/man3/pthread_affinity_np.3 @@ -0,0 +1,162 @@ +.\"- +.\" Copyright (c) 2010 Xin LI <delphij@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 January 29, 2023 +.Dt PTHREAD_AFFINITY_NP 3 +.Os +.Sh NAME +.Nm pthread_getaffinity_np , +.Nm pthread_setaffinity_np +.Nd manage CPU affinity +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft int +.Fn pthread_getaffinity_np "pthread_t td" "size_t cpusetsize" "cpuset_t *cpusetp" +.Ft int +.Fn pthread_setaffinity_np "pthread_t td" "size_t cpusetsize" "const cpuset_t *cpusetp" +.Sh DESCRIPTION +.Fn pthread_getaffinity_np +and +.Fn pthread_setaffinity_np +allow the manipulation of sets of CPUs available to the specified thread. +.Pp +Masks of type +.Ft cpuset_t +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 pthread_getaffinity_np +fails with +.Er ERANGE . +Calls to +.Fn pthread_setaffinity_np +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 +bytes. +This size is usually provided by calling +.Li sizeof(cpuset_t) +which is ultimately determined by the value of +.Dv CPU_SETSIZE +as defined in +.In sys/cpuset.h . +.Pp +.Fn pthread_getaffinity_np +retrieves the +mask from the thread specified by +.Fa td , +and stores it in the space provided by +.Fa cpusetp . +.Pp +.Fn pthread_setaffinity_np +attempts to set the mask for the thread specified by +.Fa td +to the value in +.Fa cpusetp . +.Sh RETURN VALUES +If successful, the +.Fn pthread_getaffinity_np +and +.Fn pthread_setaffinity_np +functions will return zero. +Otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_getaffinity_np +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 +call would leave a thread without a valid CPU to run on because the set +does not overlap with the thread's anonymous mask. +.It Bq Er EFAULT +The +.Fa cpusetp +pointer passed was invalid. +.It Bq Er ESRCH +The thread specified by the +.Fa td +argument could not be found. +.It Bq Er ERANGE +The +.Fa cpusetsize +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. +.El +.Sh SEE ALSO +.Xr cpuset 1 , +.Xr cpuset 2 , +.Xr cpuset_getid 2 , +.Xr cpuset_setid 2 , +.Xr pthread 3 , +.Xr pthread_attr_getaffinity_np 3 , +.Xr pthread_attr_setaffinity_np 3 , +.Xr pthread_np 3 +.Sh STANDARDS +The +.Nm pthread_getaffinity_np +and +.Nm pthread_setaffinity_np +functions are non-standard +.Fx +extensions and may be not available on other operating systems. +.Sh HISTORY +The +.Nm pthread_getaffinity_np +and +.Nm pthread_setaffinity_np +function first appeared in +.Fx 7.2 . +.Sh AUTHORS +.An -nosplit +The +.Nm pthread_getaffinity_np +and +.Nm pthread_setaffinity_np +functions were written by +.An David Xu Aq Mt davidxu@FreeBSD.org , +and this manpage was written by +.An Xin LI Aq Mt delphij@FreeBSD.org . diff --git a/static/freebsd/man3/pthread_atfork.3 b/static/freebsd/man3/pthread_atfork.3 new file mode 100644 index 00000000..5edec13e --- /dev/null +++ b/static/freebsd/man3/pthread_atfork.3 @@ -0,0 +1,114 @@ +.\" Copyright (c) 2004 Alex Vasylenko <lxv@omut.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. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.Dd June 21, 2004 +.Dt PTHREAD_ATFORK 3 +.Os +.Sh NAME +.Nm pthread_atfork +.Nd register fork handlers +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fo pthread_atfork +.Fa "void \*[lp]*prepare\*[rp]\*[lp]void\*[rp]" +.Fa "void \*[lp]*parent\*[rp]\*[lp]void\*[rp]" +.Fa "void \*[lp]*child\*[rp]\*[lp]void\*[rp]" +.Fc +.Sh DESCRIPTION +The +.Fn pthread_atfork +function declares fork handlers to be called before and after +.Xr fork 2 , +in the context of the thread that called +.Xr fork 2 . +.Pp +The handlers registered with +.Fn pthread_atfork +are called at the moments in time described below: +.Bl -tag -width ".Fa prepare" +.It Fa prepare +Before +.Xr fork 2 +processing commences in the parent process. +If more than one +.Fa prepare +handler is registered they will be called in the opposite order +they were registered. +.It Fa parent +After +.Xr fork 2 +completes in the parent process. +If more than one +.Fa parent +handler is registered they will be called in the same order +they were registered. +.It Fa child +After +.Xr fork 2 +processing completes in the child process. +If more than one +.Fa child +handler is registered they will be called in the same order +they were registered. +.El +.Pp +If no handling is desired at one or more of these three points, +a null pointer may be passed as the corresponding fork handler. +.Sh RETURN VALUES +If successful, the +.Fn pthread_atfork +function will return zero. +Otherwise an error number will be returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_atfork +function will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient table space exists to record the fork handler addresses. +.El +.Sh SEE ALSO +.Xr fork 2 , +.Xr pthread 3 +.Sh STANDARDS +The +.Fn pthread_atfork +function is expected to conform to +.St -p1003.1 . +.Sh AUTHORS +This manpage was written by +.An Alex Vasylenko Aq Mt lxv@omut.org . diff --git a/static/freebsd/man3/pthread_attr.3 b/static/freebsd/man3/pthread_attr.3 new file mode 100644 index 00000000..828195c2 --- /dev/null +++ b/static/freebsd/man3/pthread_attr.3 @@ -0,0 +1,236 @@ +.\" Copyright (C) 2000 Jason Evans <jasone@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(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 August 17, 2018 +.Dt PTHREAD_ATTR 3 +.Os +.Sh NAME +.Nm pthread_attr_init , +.Nm pthread_attr_destroy , +.Nm pthread_attr_setstack , +.Nm pthread_attr_getstack , +.Nm pthread_attr_setstacksize , +.Nm pthread_attr_getstacksize , +.Nm pthread_attr_setguardsize , +.Nm pthread_attr_getguardsize , +.Nm pthread_attr_setstackaddr , +.Nm pthread_attr_getstackaddr , +.Nm pthread_attr_setdetachstate , +.Nm pthread_attr_getdetachstate , +.Nm pthread_attr_setinheritsched , +.Nm pthread_attr_getinheritsched , +.Nm pthread_attr_setschedparam , +.Nm pthread_attr_getschedparam , +.Nm pthread_attr_setschedpolicy , +.Nm pthread_attr_getschedpolicy , +.Nm pthread_attr_setscope , +.Nm pthread_attr_getscope +.Nd thread attribute operations +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_attr_init "pthread_attr_t *attr" +.Ft int +.Fn pthread_attr_destroy "pthread_attr_t *attr" +.Ft int +.Fn pthread_attr_setstack "pthread_attr_t *attr" " void *stackaddr" "size_t stacksize" +.Ft int +.Fn pthread_attr_getstack "const pthread_attr_t * restrict attr" "void ** restrict stackaddr" "size_t * restrict stacksize" +.Ft int +.Fn pthread_attr_setstacksize "pthread_attr_t *attr" "size_t stacksize" +.Ft int +.Fn pthread_attr_getstacksize "const pthread_attr_t *restrict attr" "size_t *restrict stacksize" +.Ft int +.Fn pthread_attr_setguardsize "pthread_attr_t *attr" "size_t guardsize" +.Ft int +.Fn pthread_attr_getguardsize "const pthread_attr_t * restrict attr" "size_t * restrict guardsize" +.Ft int +.Fn pthread_attr_setstackaddr "pthread_attr_t *attr" "void *stackaddr" +.Ft int +.Fn pthread_attr_getstackaddr "const pthread_attr_t *attr" "void **stackaddr" +.Ft int +.Fn pthread_attr_setdetachstate "pthread_attr_t *attr" "int detachstate" +.Ft int +.Fn pthread_attr_getdetachstate "const pthread_attr_t *attr" "int *detachstate" +.Ft int +.Fn pthread_attr_setinheritsched "pthread_attr_t *attr" "int inheritsched" +.Ft int +.Fn pthread_attr_getinheritsched "const pthread_attr_t *restrict attr" "int *restrct inheritsched" +.Ft int +.Fn pthread_attr_setschedparam "pthread_attr_t *attr" "const struct sched_param *param" +.Ft int +.Fn pthread_attr_getschedparam "const pthread_attr_t *attr" "struct sched_param *param" +.Ft int +.Fn pthread_attr_setschedpolicy "pthread_attr_t *attr" "int policy" +.Ft int +.Fn pthread_attr_getschedpolicy "const pthread_attr_t *restrict attr" "int *restrict policy" +.Ft int +.Fn pthread_attr_setscope "pthread_attr_t *attr" "int contentionscope" +.Ft int +.Fn pthread_attr_getscope "const pthread_attr_t *restrict attr" "int *restrict contentionscope" +.Sh DESCRIPTION +Thread attributes are used to specify parameters to +.Fn pthread_create . +One attribute object can be used in multiple calls to +.Fn pthread_create , +with or without modifications between calls. +.Pp +The +.Fn pthread_attr_init +function initializes +.Fa attr +with all the default thread attributes. +.Pp +The +.Fn pthread_attr_destroy +function destroys +.Fa attr . +.Pp +The +.Fn pthread_attr_set* +functions set the attribute that corresponds to each function name. +.Pp +The +.Fn pthread_attr_get* +functions copy the value of the attribute that corresponds to each function name +to the location pointed to by the second function parameter. +.Sh RETURN VALUES +If successful, these functions return 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_attr_init +function will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Out of memory. +.El +.Pp +The +.Fn pthread_attr_destroy +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.El +.Pp +The +.Fn pthread_attr_setstacksize +and +.Fn pthread_attr_setstack +functions will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa stacksize +is less than +.Dv PTHREAD_STACK_MIN . +.El +.Pp +The +.Fn pthread_attr_setdetachstate +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa detachstate . +.El +.Pp +The +.Fn pthread_attr_setinheritsched +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.El +.Pp +The +.Fn pthread_attr_setschedparam +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.It Bq Er ENOTSUP +Invalid value for +.Fa param . +.El +.Pp +The +.Fn pthread_attr_setschedpolicy +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.It Bq Er ENOTSUP +Invalid or unsupported value for +.Fa policy . +.El +.Pp +The +.Fn pthread_attr_setscope +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.It Bq Er ENOTSUP +Invalid or unsupported value for +.Fa contentionscope . +.El +.Sh SEE ALSO +.Xr pthread_attr_affinity_np 3 , +.Xr pthread_attr_get_np 3 , +.Xr pthread_create 3 +.Sh STANDARDS +.Fn pthread_attr_init , +.Fn pthread_attr_destroy , +.Fn pthread_attr_setstacksize , +.Fn pthread_attr_getstacksize , +.Fn pthread_attr_setstackaddr , +.Fn pthread_attr_getstackaddr , +.Fn pthread_attr_setdetachstate , +and +.Fn pthread_attr_getdetachstate +functions conform to +.St -p1003.1-96 +.Pp +The +.Fn pthread_attr_setinheritsched , +.Fn pthread_attr_getinheritsched , +.Fn pthread_attr_setschedparam , +.Fn pthread_attr_getschedparam , +.Fn pthread_attr_setschedpolicy , +.Fn pthread_attr_getschedpolicy , +.Fn pthread_attr_setscope , +and +.Fn pthread_attr_getscope +functions conform to +.St -susv2 diff --git a/static/freebsd/man3/pthread_attr_affinity_np.3 b/static/freebsd/man3/pthread_attr_affinity_np.3 new file mode 100644 index 00000000..0589213c --- /dev/null +++ b/static/freebsd/man3/pthread_attr_affinity_np.3 @@ -0,0 +1,161 @@ +.\"- +.\" Copyright (c) 2010 Xin LI <delphij@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 January 29, 2023 +.Dt PTHREAD_ATTR_AFFINITY_NP 3 +.Os +.Sh NAME +.Nm pthread_attr_getaffinity_np , +.Nm pthread_attr_setaffinity_np +.Nd manage CPU affinity in thread attribute objects +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft int +.Fn pthread_attr_getaffinity_np "const pthread_attr_t *pattr" "size_t cpusetsize" "cpuset_t *cpusetp" +.Ft int +.Fn pthread_attr_setaffinity_np "pthread_attr_t *pattr" "size_t cpusetsize" "const cpuset_t *cpusetp" +.Sh DESCRIPTION +The +.Fn pthread_attr_getaffinity_np +and +.Fn pthread_attr_setaffinity_np +functions allow the manipulation of sets of CPUs available to the specified thread attribute object. +.Pp +Masks of type +.Ft cpuset_t +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 pthread_attr_getaffinity_np +fails with +.Er ERANGE . +Calls to +.Fn pthread_attr_setaffinity_np +tolerate masks of any size with no restrictions. +.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 pthread_attr_setaffinity_np +fail with +.Er EINVAL . +.Pp +The supplied mask should have a size of +.Fa cpusetsize +bytes. +This size is usually provided by calling +.Li sizeof(cpuset_t) +which is ultimately determined by the value of +.Dv CPU_SETSIZE +as defined in +.In sys/cpuset.h . +.Pp +.Fn pthread_attr_getaffinity_np +retrieves the +mask from the thread attribute object specified by +.Fa pattr , +and stores it in the space provided by +.Fa cpusetp . +.Pp +.Fn pthread_attr_setaffinity_np +sets the mask for the thread attribute object specified by +.Fa pattr +to the value in +.Fa cpusetp . +.Sh RETURN VALUES +If successful, the +.Fn pthread_attr_getaffinity_np +and +.Fn pthread_attr_setaffinity_np +functions will return zero. +Otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_attr_getaffinity_np +functions will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa pattr +or the attribute specified by it is +.Dv NULL . +.It Bq Er ERANGE +The +.Fa cpusetsize +is too small. +.El +.Pp +The +.Fn pthread_attr_setaffinity_np +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa pattr +or the attribute specified by it is +.Dv NULL . +.It Bq Er EINVAL +The +.Fa cpusetp +specified a CPU that was outside the set supported by the kernel. +.It Bq Er ENOMEM +Insufficient memory exists to store the cpuset mask. +.El +.Sh SEE ALSO +.Xr cpuset 1 , +.Xr cpuset 2 , +.Xr cpuset_getid 2 , +.Xr cpuset_setid 2 , +.Xr pthread_getaffinity_np 3 , +.Xr pthread_np 3 , +.Xr pthread_setaffinity_np 3 +.Sh STANDARDS +The +.Nm pthread_attr_getaffinity_np +and +.Nm pthread_attr_setaffinity_np +functions are non-standard +.Fx +extensions and may be not available on other operating systems. +.Sh HISTORY +The +.Nm pthread_attr_getaffinity_np +and +.Nm pthread_attr_setaffinity_np +functions first appeared in +.Fx 7.2 . +.Sh AUTHORS +.An -nosplit +The +.Nm pthread_attr_getaffinity_np +and +.Nm pthread_attr_setaffinity_np +functions were written by +.An David Xu Aq Mt davidxu@FreeBSD.org , +and this manpage was written by +.An Xin LI Aq Mt delphij@FreeBSD.org . diff --git a/static/freebsd/man3/pthread_attr_get_np.3 b/static/freebsd/man3/pthread_attr_get_np.3 new file mode 100644 index 00000000..07153586 --- /dev/null +++ b/static/freebsd/man3/pthread_attr_get_np.3 @@ -0,0 +1,128 @@ +.\" 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 +.\" 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 January 5, 2024 +.Dt PTHREAD_ATTR_GET_NP 3 +.Os +.Sh NAME +.Nm pthread_attr_get_np +.Nd get attributes of an existing thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft int +.Fn pthread_attr_get_np "pthread_t pid" "pthread_attr_t *dst" +.Sh DESCRIPTION +The +.Fn pthread_attr_get_np +function is used to retrieve the attributes of the specified thread into an +existing +.Vt pthread_attr_t +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 +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 +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 tid) +{ + pthread_attr_t attr; + size_t 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 +The +.Fn pthread_attr_get_np +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +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 , +.Xr pthread_attr_getschedparam 3 , +.Xr pthread_attr_getschedpolicy 3 , +.Xr pthread_attr_getscope 3 , +.Xr pthread_attr_getstack 3 , +.Xr pthread_attr_getstackaddr 3 , +.Xr pthread_attr_getstacksize 3 , +.Xr pthread_attr_init 3 , +.Xr pthread_np 3 +.Sh AUTHORS +The +.Fn pthread_attr_get_np +function and this manual page were written by +.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/static/freebsd/man3/pthread_attr_setcreatesuspend_np.3 b/static/freebsd/man3/pthread_attr_setcreatesuspend_np.3 new file mode 100644 index 00000000..3d2f84a4 --- /dev/null +++ b/static/freebsd/man3/pthread_attr_setcreatesuspend_np.3 @@ -0,0 +1,71 @@ +.\" 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. +.\" +.Dd October 12, 2021 +.Dt PTHREAD_ATTR_SETCREATESUSPEND_NP 3 +.Os +.Sh NAME +.Nm pthread_attr_setcreatesuspend_np +.Nd prepare attribute for creation of suspended thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft int +.Fn pthread_attr_setcreatesuspend_np "pthread_attr_t *attr" +.Sh DESCRIPTION +The +.Fn pthread_attr_setcreatesuspend_np +instructs +.Xr pthread_create 3 +that the thread created with the +.Fa attr +attribute +should be created and left in a suspended state until explicitly resumed +by the call to +.Fn pthread_resume_np +or +.Fn pthread_resume_all_np . +.Sh RETURN VALUES +.Rv -std pthread_attr_setcreatesuspend_np +.Sh ERRORS +The +.Fn pthread_attr_setcreatesuspend_np +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_attr_destroy 3 , +.Xr pthread_attr_init 3 , +.Xr pthread_create 3 , +.Xr pthread_np 3 , +.Xr pthread_resume_all_np 3 , +.Xr pthread_resume_np 3 +.Sh AUTHORS +This manual page was written by +.An Alexey Zelkin Aq Mt phantom@FreeBSD.org . diff --git a/static/freebsd/man3/pthread_barrier_destroy.3 b/static/freebsd/man3/pthread_barrier_destroy.3 new file mode 100644 index 00000000..06c8b97e --- /dev/null +++ b/static/freebsd/man3/pthread_barrier_destroy.3 @@ -0,0 +1,154 @@ +.\" Copyright (c) 2004 Michael Telahun Makonnen +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 17, 2018 +.Dt PTHREAD_BARRIER 3 +.Os +.Sh NAME +.Nm pthread_barrier_destroy , pthread_barrier_init , pthread_barrier_wait +.Nd "destroy, initialize or wait on a barrier object" +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_barrier_destroy "pthread_barrier_t *barrier" +.Ft int +.Fn pthread_barrier_init "pthread_barrier_t *restrict barrier" "const pthread_barrierattr_t *attr" "unsigned count" +.Ft int +.Fn pthread_barrier_wait "pthread_barrier_t *barrier" +.Sh DESCRIPTION +The +.Fn pthread_barrier_init +function will initialize +.Fa barrier +with attributes specified in +.Fa attr , +or if it is +.Dv NULL , +with default attributes. +The number of threads that must call +.Fn pthread_barrier_wait +before any of the waiting threads can be +released is specified by +.Fa count . +The +.Fn pthread_barrier_destroy +function will destroy +.Fa barrier +and release any resources that may have been allocated on its behalf. +.Pp +The +.Fn pthread_barrier_wait +function will synchronize calling threads at +.Fa barrier . +The threads will be blocked from +making further progress until +a sufficient number of threads calls this function. +The number of threads that must call it before +any of them will be released is determined by the +.Fa count +argument to +.Fn pthread_barrier_init . +Once the threads have been released the barrier will be reset. +.Sh IMPLEMENTATION NOTES +In +.Lb libthr +the +.Dv PTHREAD_BARRIER_SERIAL_THREAD +return value will +always be returned by the last thread to reach the barrier. +.Sh RETURN VALUES +If successful, +both +.Fn pthread_barrier_destroy +and +.Fn pthread_barrier_init +will return zero. +Otherwise, an error number will be returned to indicate the error. +If the call to +.Fn pthread_barrier_wait +is successful, all but one of the threads will return zero. +That one thread will return +.Dv PTHREAD_BARRIER_SERIAL_THREAD . +Otherwise, an error number will be returned to indicate the error. +.Pp +None of these functions will return +.Er EINTR . +.Sh ERRORS +The +.Fn pthread_barrier_destroy +function will fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +An attempt was made to destroy +.Fa barrier +while it was in use. +.El +.Pp +The +.Fn pthread_barrier_destroy +and +.Fn pthread_barrier_wait +functions may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa barrier +is invalid. +.El +.Pp +The +.Fn pthread_barrier_init +function will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system lacks resources, +other than memory, +to initialize +.Fa barrier . +.It Bq Er EINVAL +The +.Fa count +argument is less than 1. +.It Bq Er ENOMEM +Insufficient memory to initialize +.Fa barrier . +.El +.Sh SEE ALSO +.Xr pthread_barrierattr 3 +.Sh HISTORY +The +.Fn pthread_barrier_destroy , +.Fn pthread_barrier_init +and +.Fn pthread_barrier_wait +functions first appeared in +.Lb libkse +in +.Fx 5.2 , +and in +.Lb libthr +in +.Fx 5.3 . diff --git a/static/freebsd/man3/pthread_barrierattr.3 b/static/freebsd/man3/pthread_barrierattr.3 new file mode 100644 index 00000000..1f5243f9 --- /dev/null +++ b/static/freebsd/man3/pthread_barrierattr.3 @@ -0,0 +1,137 @@ +.\" Copyright (c) 2004 Michael Telahun Makonnen +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 17, 2018 +.Dt PTHREAD_BARRIERATTR 3 +.Os +.Sh NAME +.Nm pthread_barrierattr_destroy , pthread_barrierattr_getpshared , +.Nm pthread_barrierattr_init , pthread_barrierattr_setpshared +.Nd "manipulate a barrier attribute object" +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_barrierattr_destroy "pthread_barrierattr_t *attr" +.Ft int +.Fo pthread_barrierattr_getpshared +.Fa "const pthread_barrierattr_t *restrict attr" "int *restrict pshared" +.Fc +.Ft int +.Fn pthread_barrierattr_init "pthread_barrierattr_t *attr" +.Ft int +.Fo pthread_barrierattr_setpshared +.Fa "pthread_barrierattr_t *attr" "int pshared" +.Fc +.Sh DESCRIPTION +The +.Fn pthread_barrierattr_init +function will initialize +.Fa attr +with default attributes. +The +.Fn pthread_barrierattr_destroy +function will destroy +.Fa attr +and release any resources that may have been allocated on its behalf. +.Pp +The +.Fn pthread_barrierattr_getpshared +function will put the value of the process-shared attribute from +.Fa attr +into the memory area pointed to by +.Fa pshared . +The +.Fn pthread_barrierattr_setpshared +function will set 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 barrier object it is attached to may only be accessed by +threads in the same process as the one that created the object. +.It Dv PTHREAD_PROCESS_SHARED +The barrier object it is attached to may be accessed by +threads in processes other than the one that created the object. +.El +.Sh RETURN VALUES +If successful, all these functions will return zero. +Otherwise, an error number will be returned to indicate the error. +.Pp +None of these functions will return +.Er EINTR . +.Sh ERRORS +The +.Fn pthread_barrierattr_destroy , +.Fn pthread_barrierattr_getpshared +and +.Fn pthread_barrierattr_setpshared +functions may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Pp +The +.Fn pthread_barrierattr_init +function will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient memory to initialize the barrier attribute object +.Fa attr . +.El +.Pp +The +.Fn pthread_barrierattr_setpshared +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified in +.Fa pshared +is not one of the allowed values. +.El +.Sh SEE ALSO +.Xr pthread_barrier_destroy 3 , +.Xr pthread_barrier_init 3 , +.Xr pthread_barrier_wait 3 +.Sh HISTORY +The +.Fn pthread_barrierattr_* +functions first appeared in +.Lb libkse +in +.Fx 5.2 , +and in +.Lb libthr +in +.Fx 5.3 . +Support for process-shared barriers appeared in +.Fx 11.0 . diff --git a/static/freebsd/man3/pthread_cancel.3 b/static/freebsd/man3/pthread_cancel.3 new file mode 100644 index 00000000..33a00300 --- /dev/null +++ b/static/freebsd/man3/pthread_cancel.3 @@ -0,0 +1,80 @@ +.Dd January 17, 1999 +.Dt PTHREAD_CANCEL 3 +.Os +.Sh NAME +.Nm pthread_cancel +.Nd cancel execution of a thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_cancel "pthread_t thread" +.Sh DESCRIPTION +The +.Fn pthread_cancel +function requests that +.Fa thread +be canceled. +The target thread's cancelability state and type determines +when the cancellation takes effect. +When the cancellation is acted on, +the cancellation cleanup handlers for +.Fa thread +are called. +When the last cancellation cleanup handler returns, +the thread-specific data destructor functions will be called for +.Fa thread . +When the last destructor function returns, +.Fa thread +will be terminated. +.Pp +The cancellation processing in the target thread runs asynchronously with +respect to the calling thread returning from +.Fn pthread_cancel . +.Pp +A status of +.Dv PTHREAD_CANCELED +is made available to any threads joining with the target. +The symbolic +constant +.Dv PTHREAD_CANCELED +expands to a constant expression of type +.Ft "(void *)" , +whose value matches no pointer to an object in memory nor the value +.Dv NULL . +.Sh RETURN VALUES +If successful, the +.Fn pthread_cancel +functions will return zero. +Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_cancel +function will fail if: +.Bl -tag -width Er +.It Bq Er ESRCH +No thread could be found corresponding to that specified by the given +thread ID. +.El +.Sh SEE ALSO +.Xr pthread_cleanup_pop 3 , +.Xr pthread_cleanup_push 3 , +.Xr pthread_exit 3 , +.Xr pthread_join 3 , +.Xr pthread_setcancelstate 3 , +.Xr pthread_setcanceltype 3 , +.Xr pthread_testcancel 3 +.Sh STANDARDS +The +.Fn pthread_cancel +function conforms to +.St -p1003.1-96 . +.Sh AUTHORS +This manual page was written by +.An David Leonard Aq Mt d@openbsd.org +for the +.Ox +implementation of +.Fn pthread_cancel . diff --git a/static/freebsd/man3/pthread_cleanup_pop.3 b/static/freebsd/man3/pthread_cleanup_pop.3 new file mode 100644 index 00000000..2747624b --- /dev/null +++ b/static/freebsd/man3/pthread_cleanup_pop.3 @@ -0,0 +1,72 @@ +.\" Copyright (c) 1997 Brian Cully <shmit@kublai.com> +.\" 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 author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 October 25, 2014 +.Dt PTHREAD_CLEANUP_POP 3 +.Os +.Sh NAME +.Nm pthread_cleanup_pop +.Nd call the first cleanup routine +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft void +.Fn pthread_cleanup_pop "int execute" +.Sh DESCRIPTION +The +.Fn pthread_cleanup_pop +function pops the top cleanup routine off of the current threads cleanup +routine stack, and, if +.Fa execute +is non-zero, it will execute the function. +If there is no cleanup routine +then +.Fn pthread_cleanup_pop +does nothing. +.Pp +The +.Fn pthread_cleanup_pop +function is implemented as a macro that closes a block. +Invocations of this function must appear as standalone statements that are +paired with an earlier call of +.Xr pthread_cleanup_push 3 +in the same lexical scope. +.Sh RETURN VALUES +The +.Fn pthread_cleanup_pop +function does not return any value. +.Sh ERRORS +None +.Sh SEE ALSO +.Xr pthread_cleanup_push 3 , +.Xr pthread_exit 3 +.Sh STANDARDS +The +.Fn pthread_cleanup_pop +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_cleanup_push.3 b/static/freebsd/man3/pthread_cleanup_push.3 new file mode 100644 index 00000000..327c2fc3 --- /dev/null +++ b/static/freebsd/man3/pthread_cleanup_push.3 @@ -0,0 +1,74 @@ +.\" Copyright (c) 1997 Brian Cully <shmit@kublai.com> +.\" 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 author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 October 25, 2014 +.Dt PTHREAD_CLEANUP_PUSH 3 +.Os +.Sh NAME +.Nm pthread_cleanup_push +.Nd add a cleanup function for thread exit +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft void +.Fn pthread_cleanup_push "void \*[lp]*cleanup_routine\*[rp]\*[lp]void *\*[rp]" "void *arg" +.Sh DESCRIPTION +The +.Fn pthread_cleanup_push +function adds +.Fa cleanup_routine +to the top of the stack of cleanup handlers that +get called when the current thread exits. +.Pp +When +.Fa cleanup_routine +is called, it is passed +.Fa arg +as its only argument. +.Pp +The +.Fn pthread_cleanup_push +function is implemented as a macro that opens a new block. +Invocations of this function must appear as standalone statements that are +paired with a later call of +.Xr pthread_cleanup_pop 3 +in the same lexical scope. +.Sh RETURN VALUES +The +.Fn pthread_cleanup_push +function does not return any value. +.Sh ERRORS +None +.Sh SEE ALSO +.Xr pthread_cleanup_pop 3 , +.Xr pthread_exit 3 +.Sh STANDARDS +The +.Fn pthread_cleanup_push +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_cond_broadcast.3 b/static/freebsd/man3/pthread_cond_broadcast.3 new file mode 100644 index 00000000..77c1a2c2 --- /dev/null +++ b/static/freebsd/man3/pthread_cond_broadcast.3 @@ -0,0 +1,70 @@ +.\" Copyright (c) 1997 Brian Cully <shmit@kublai.com> +.\" 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 author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 July 28, 1998 +.Dt PTHREAD_COND_BROADCAST 3 +.Os +.Sh NAME +.Nm pthread_cond_broadcast +.Nd unblock all threads waiting for a condition variable +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_cond_broadcast "pthread_cond_t *cond" +.Sh DESCRIPTION +The +.Fn pthread_cond_broadcast +function unblocks all threads waiting for the condition variable +.Fa cond . +.Sh RETURN VALUES +If successful, the +.Fn pthread_cond_broadcast +function will return zero, otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_cond_broadcast +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa cond +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_cond_destroy 3 , +.Xr pthread_cond_init 3 , +.Xr pthread_cond_signal 3 , +.Xr pthread_cond_timedwait 3 , +.Xr pthread_cond_wait 3 +.Sh STANDARDS +The +.Fn pthread_cond_broadcast +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_cond_destroy.3 b/static/freebsd/man3/pthread_cond_destroy.3 new file mode 100644 index 00000000..ec07b030 --- /dev/null +++ b/static/freebsd/man3/pthread_cond_destroy.3 @@ -0,0 +1,77 @@ +.\" Copyright (c) 1997 Brian Cully <shmit@kublai.com> +.\" 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 author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 July 28, 1998 +.Dt PTHREAD_COND_DESTROY 3 +.Os +.Sh NAME +.Nm pthread_cond_destroy +.Nd destroy a condition variable +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_cond_destroy "pthread_cond_t *cond" +.Sh DESCRIPTION +The +.Fn pthread_cond_destroy +function frees the resources allocated by the condition variable +.Fa cond . +.Sh IMPLEMENTATION NOTES +A condition variable can be destroyed immediately after all the threads that +are blocked on it are awakened. +.Sh RETURN VALUES +If successful, the +.Fn pthread_cond_destroy +function will return zero, otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_cond_destroy +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa cond +is invalid. +.It Bq Er EBUSY +The variable +.Fa cond +is locked by another thread. +.El +.Sh SEE ALSO +.Xr pthread_cond_broadcast 3 , +.Xr pthread_cond_init 3 , +.Xr pthread_cond_signal 3 , +.Xr pthread_cond_timedwait 3 , +.Xr pthread_cond_wait 3 +.Sh STANDARDS +The +.Fn pthread_cond_destroy +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_cond_init.3 b/static/freebsd/man3/pthread_cond_init.3 new file mode 100644 index 00000000..8d3dd79d --- /dev/null +++ b/static/freebsd/man3/pthread_cond_init.3 @@ -0,0 +1,81 @@ +.\" Copyright (c) 1997 Brian Cully <shmit@kublai.com> +.\" 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 author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 August 17, 2018 +.Dt PTHREAD_COND_INIT 3 +.Os +.Sh NAME +.Nm pthread_cond_init +.Nd create a condition variable +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_cond_init "pthread_cond_t *restrict cond" "const pthread_condattr_t *restrict attr" +.Sh DESCRIPTION +The +.Fn pthread_cond_init +function creates a new condition variable, with attributes specified with +.Fa attr . +If +.Fa attr +is NULL the default attributes are used. +.Sh RETURN VALUES +If successful, the +.Fn pthread_cond_init +function will return zero and put the new condition variable id into +.Fa cond , +otherwise an error number will be returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_cond_init +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.It Bq Er ENOMEM +The process cannot allocate enough memory to create another condition +variable. +.It Bq Er EAGAIN +The system temporarily lacks the resources to create another condition +variable. +.El +.Sh SEE ALSO +.Xr pthread_cond_broadcast 3 , +.Xr pthread_cond_destroy 3 , +.Xr pthread_cond_signal 3 , +.Xr pthread_cond_timedwait 3 , +.Xr pthread_cond_wait 3 , +.Xr pthread_condattr 3 +.Sh STANDARDS +The +.Fn pthread_cond_init +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_cond_signal.3 b/static/freebsd/man3/pthread_cond_signal.3 new file mode 100644 index 00000000..5eb65650 --- /dev/null +++ b/static/freebsd/man3/pthread_cond_signal.3 @@ -0,0 +1,70 @@ +.\" Copyright (c) 1997 Brian Cully <shmit@kublai.com> +.\" 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 author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 July 28, 1998 +.Dt PTHREAD_COND_SIGNAL 3 +.Os +.Sh NAME +.Nm pthread_cond_signal +.Nd unblock a thread waiting for a condition variable +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_cond_signal "pthread_cond_t *cond" +.Sh DESCRIPTION +The +.Fn pthread_cond_signal +function unblocks one thread waiting for the condition variable +.Fa cond . +.Sh RETURN VALUES +If successful, the +.Fn pthread_cond_signal +function will return zero, otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_cond_signal +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa cond +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_cond_broadcast 3 , +.Xr pthread_cond_destroy 3 , +.Xr pthread_cond_init 3 , +.Xr pthread_cond_timedwait 3 , +.Xr pthread_cond_wait 3 +.Sh STANDARDS +The +.Fn pthread_cond_signal +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_cond_timedwait.3 b/static/freebsd/man3/pthread_cond_timedwait.3 new file mode 100644 index 00000000..d955bf85 --- /dev/null +++ b/static/freebsd/man3/pthread_cond_timedwait.3 @@ -0,0 +1,99 @@ +.\" Copyright (c) 1997 Brian Cully <shmit@kublai.com> +.\" 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 author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 May 9, 2010 +.Dt PTHREAD_COND_TIMEDWAIT 3 +.Os +.Sh NAME +.Nm pthread_cond_timedwait +.Nd "wait on a condition variable for a specific amount of time" +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_cond_timedwait "pthread_cond_t *cond" "pthread_mutex_t *mutex" "const struct timespec *abstime" +.Sh DESCRIPTION +The +.Fn pthread_cond_timedwait +function atomically blocks the current thread waiting on the condition +variable specified by +.Fa cond , +and releases the mutex specified by +.Fa mutex . +The waiting thread unblocks only after another thread calls +.Xr pthread_cond_signal 3 , +or +.Xr pthread_cond_broadcast 3 +with the same condition variable, or if the system time reaches the +time specified in +.Fa abstime , +and the current thread reacquires the lock on +.Fa mutex . +.Pp +The clock used to measure +.Fa abstime +can be specified during creation of the condition variable using +.Xr pthread_condattr_setclock 3 . +.Sh RETURN VALUES +If successful, the +.Fn pthread_cond_timedwait +function will return zero. +Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_cond_timedwait +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa cond , +.Fa mutex +or +.Fa abstime +is invalid. +.It Bq Er ETIMEDOUT +The system time has reached or exceeded the time specified in +.Fa abstime . +.It Bq Er EPERM +The specified +.Fa mutex +was not locked by the calling thread. +.El +.Sh SEE ALSO +.Xr pthread_cond_broadcast 3 , +.Xr pthread_cond_destroy 3 , +.Xr pthread_cond_init 3 , +.Xr pthread_cond_signal 3 , +.Xr pthread_cond_wait 3 , +.Xr pthread_condattr_setclock 3 +.Sh STANDARDS +The +.Fn pthread_cond_timedwait +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_cond_wait.3 b/static/freebsd/man3/pthread_cond_wait.3 new file mode 100644 index 00000000..c09e7aa6 --- /dev/null +++ b/static/freebsd/man3/pthread_cond_wait.3 @@ -0,0 +1,99 @@ +.\" Copyright (c) 1997 Brian Cully <shmit@kublai.com> +.\" 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 author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 August 7, 2019 +.Dt PTHREAD_COND_WAIT 3 +.Os +.Sh NAME +.Nm pthread_cond_wait +.Nd wait on a condition variable +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_cond_wait "pthread_cond_t *restrict cond" "pthread_mutex_t *restrict mutex" +.Sh DESCRIPTION +The +.Fn pthread_cond_wait +function atomically blocks the current thread waiting on the condition +variable specified by +.Fa cond , +and releases the mutex specified by +.Fa mutex . +The waiting thread unblocks only after another thread calls +.Xr pthread_cond_signal 3 , +or +.Xr pthread_cond_broadcast 3 +with the same condition variable, and the current thread reacquires the lock +on +.Fa mutex . +.Sh RETURN VALUES +If successful, the +.Fn pthread_cond_wait +function will return zero. +Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_cond_wait +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa cond +or the value specified by +.Fa mutex +is invalid. +.It Bq Er EPERM +The specified +.Fa mutex +was not locked by the calling thread. +.It Bq Er EOWNERDEAD +The argument +.Fa mutex +points to a robust mutex and the process containing the previous owning +thread terminated while holding the mutex lock. +The lock was granted to the caller and it is up to the new owner +to make the state consistent. +.It Bq Er ENOTRECOVERABLE +The state protected by the +.Fa mutex +is not recoverable. +.El +.Sh SEE ALSO +.Xr pthread_cond_broadcast 3 , +.Xr pthread_cond_destroy 3 , +.Xr pthread_cond_init 3 , +.Xr pthread_cond_signal 3 , +.Xr pthread_cond_timedwait 3 , +.Xr pthread_mutex_consistent 3 +.Sh STANDARDS +The +.Fn pthread_cond_wait +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_condattr.3 b/static/freebsd/man3/pthread_condattr.3 new file mode 100644 index 00000000..33ad904f --- /dev/null +++ b/static/freebsd/man3/pthread_condattr.3 @@ -0,0 +1,170 @@ +.\" Copyright (C) 2000 Jason Evans <jasone@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(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 October 27, 2023 +.Dt PTHREAD_CONDATTR 3 +.Os +.Sh NAME +.Nm pthread_condattr_init , +.Nm pthread_condattr_destroy , +.Nm pthread_condattr_getclock , +.Nm pthread_condattr_setclock , +.Nm pthread_condattr_getpshared , +.Nm pthread_condattr_setpshared +.Nd condition attribute operations +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_condattr_init "pthread_condattr_t *attr" +.Ft int +.Fn pthread_condattr_destroy "pthread_condattr_t *attr" +.Ft int +.Fo pthread_condattr_getclock +.Fa "pthread_condattr_t * restrict attr" "clockid_t * restrict clock_id" +.Fc +.Ft int +.Fn pthread_condattr_setclock "pthread_condattr_t *attr" "clockid_t clock_id" +.Ft int +.Fo pthread_condattr_getpshared +.Fa "pthread_condattr_t * restrict attr" "int * restrict pshared" +.Fc +.Ft int +.Fn pthread_condattr_setpshared "pthread_condattr_t *attr" "int pshared" +.Sh DESCRIPTION +Condition attribute objects are used to specify parameters to +.Fn pthread_cond_init . +.Pp +The +.Fn pthread_condattr_init +function initializes a condition attribute object with the default attributes. +.Pp +The +.Fn pthread_condattr_destroy +function destroys a condition attribute object. +.Pp +The +.Fn pthread_condattr_getclock +function will put the value of the clock attribute from +.Fa attr +into the memory area pointed to by +.Fa clock_id . +The +.Fn pthread_condattr_setclock +function will set the clock attribute of +.Fa attr +to the value specified in +.Fa clock_id . +The clock attribute affects the interpretation of +.Fa abstime +in +.Xr pthread_cond_timedwait 3 +and may be set to +.Dv CLOCK_REALTIME +(default), +.Dv CLOCK_TAI , +or +.Dv CLOCK_MONOTONIC . +.Pp +The +.Fn pthread_condattr_getpshared +function will put the value of the process-shared attribute from +.Fa attr +into the memory area pointed to by +.Fa pshared . +The +.Fn pthread_condattr_setpshared +function will set 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 condition variable it is attached to may only be accessed by +threads in the same process as the one that created the object. +.It Dv PTHREAD_PROCESS_SHARED +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. +.Sh ERRORS +The +.Fn pthread_condattr_init +function will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Out of memory. +.El +.Pp +The +.Fn pthread_condattr_destroy +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.El +.Pp +The +.Fn pthread_condattr_setclock +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified in +.Fa clock_id +is not one of the allowed values. +.El +.Pp +The +.Fn pthread_condattr_setpshared +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified in +.Fa pshared +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 +The +.Fn pthread_condattr_init +and +.Fn pthread_condattr_destroy +functions conform to +.St -p1003.1-96 diff --git a/static/freebsd/man3/pthread_create.3 b/static/freebsd/man3/pthread_create.3 new file mode 100644 index 00000000..2d43ac7b --- /dev/null +++ b/static/freebsd/man3/pthread_create.3 @@ -0,0 +1,147 @@ +.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 August 17, 2018 +.Dt PTHREAD_CREATE 3 +.Os +.Sh NAME +.Nm pthread_create +.Nd create a new thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_create "pthread_t *restrict thread" "const pthread_attr_t *restrict attr" "void *(*start_routine)(void *)" "void *restrict arg" +.Sh DESCRIPTION +The +.Fn pthread_create +function is used to create a new thread, with attributes specified by +.Fa attr , +within a process. +If +.Fa attr +is +.Dv NULL , +the default attributes are used. +If the attributes specified by +.Fa attr +are modified later, the thread's attributes are not affected. +Upon +successful completion +.Fn pthread_create +will store the ID of the created thread in the location specified by +.Fa thread . +.Pp +The thread is created executing +.Fa start_routine +with +.Fa arg +as its sole argument. +If the +.Fa start_routine +returns, the effect is as if there was an implicit call to +.Fn pthread_exit +using the return value of +.Fa start_routine +as the exit status. +Note that the thread in which +.Fn main +was originally invoked differs from this. +When it returns from +.Fn main , +the effect is as if there was an implicit call to +.Fn exit +using the return value of +.Fn main +as the exit status. +.Pp +The signal state of the new thread is initialized as: +.Bl -bullet -offset indent +.It +The signal mask is inherited from the creating thread. +.It +The set of signals pending for the new thread is empty. +.El +.Sh RETURN VALUES +If successful, the +.Fn pthread_create +function will return zero. +Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_create +function can return any of the following errors: +.Bl -tag -width Er +.It Bq Er ENOMEM +The system lacked the necessary resources to create another thread. +.It Bq Er EAGAIN +The system-imposed limit on the total number of threads in a process +.Dv [PTHREAD_THREADS_MAX] +would be exceeded. +.It Bq Er EAGAIN +The +.Dv RACCT_NTHR +limit would be exceeded; see +.Xr racct 2 . +.It Bq Er EPERM +The caller does not have permission to set the scheduling parameters or +scheduling policy. +.It Bq Er EINVAL +A value specified by +.Fa attr +is invalid. +.It Bq Er EDEADLK +The CPU set specified by +.Fa attr +would prevent the thread from running on any CPU. +.It Bq Er EFAULT +The stack base specified by +.Fa attr +is invalid, or the kernel was unable to put required +initial data on the stack. +.El +.Sh SEE ALSO +.Xr cpuset_setaffinity 2 , +.Xr fork 2 , +.Xr racct 2 , +.Xr thr_new 2 , +.Xr pthread_attr 3 , +.Xr pthread_cancel 3 , +.Xr pthread_cleanup_pop 3 , +.Xr pthread_cleanup_push 3 , +.Xr pthread_exit 3 , +.Xr pthread_join 3 +.Sh STANDARDS +The +.Fn pthread_create +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_detach.3 b/static/freebsd/man3/pthread_detach.3 new file mode 100644 index 00000000..93bead1c --- /dev/null +++ b/static/freebsd/man3/pthread_detach.3 @@ -0,0 +1,89 @@ +.\" Copyright (c) 1996-1998 John Birrell <jb@cimlogic.com.au>. +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 4, 1996 +.Dt PTHREAD_DETACH 3 +.Os +.Sh NAME +.Nm pthread_detach +.Nd detach a thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_detach "pthread_t thread" +.Sh DESCRIPTION +The +.Fn pthread_detach +function is used to indicate to the implementation that storage for the +thread +.Fa thread +can be reclaimed when the thread terminates. +If +.Fa thread +has not terminated, +.Fn pthread_detach +will not cause it to terminate. +The effect of multiple +.Fn pthread_detach +calls on the same target thread is unspecified. +.Sh RETURN VALUES +If successful, the +.Fn pthread_detach +function will return zero. +Otherwise an error number will be returned to +indicate the error. +Note that the function does not change the value +of errno as it did for some drafts of the standard. +These early drafts +also passed a pointer to pthread_t as the argument. +Beware! +.Sh ERRORS +The +.Fn pthread_detach +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The implementation has detected that the value specified by +.Fa thread +does not refer to a joinable thread. +.It Bq Er ESRCH +No thread could be found corresponding to that specified by the given +thread ID, +.Fa thread . +.El +.Sh SEE ALSO +.Xr pthread_join 3 +.Sh STANDARDS +The +.Fn pthread_detach +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_equal.3 b/static/freebsd/man3/pthread_equal.3 new file mode 100644 index 00000000..6ef861bc --- /dev/null +++ b/static/freebsd/man3/pthread_equal.3 @@ -0,0 +1,67 @@ +.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 4, 1996 +.Dt PTHREAD_EQUAL 3 +.Os +.Sh NAME +.Nm pthread_equal +.Nd compare thread IDs +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_equal "pthread_t t1" "pthread_t t2" +.Sh DESCRIPTION +The +.Fn pthread_equal +function compares the thread IDs +.Fa t1 +and +.Fa t2 . +.Sh RETURN VALUES +The +.Fn pthread_equal +function will return non-zero if the thread IDs +.Fa t1 +and +.Fa t2 +correspond to the same thread, otherwise it will return zero. +.Sh ERRORS +None. +.Sh SEE ALSO +.Xr pthread_create 3 , +.Xr pthread_exit 3 +.Sh STANDARDS +The +.Fn pthread_equal +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_exit.3 b/static/freebsd/man3/pthread_exit.3 new file mode 100644 index 00000000..5c8f6ac4 --- /dev/null +++ b/static/freebsd/man3/pthread_exit.3 @@ -0,0 +1,105 @@ +.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 March 15, 2014 +.Dt PTHREAD_EXIT 3 +.Os +.Sh NAME +.Nm pthread_exit +.Nd terminate the calling thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft void +.Fn pthread_exit "void *value_ptr" +.Sh DESCRIPTION +The +.Fn pthread_exit +function terminates the calling thread and makes the value +.Fa value_ptr +available to any successful join with the terminating thread. +Any +cancellation cleanup handlers that have been pushed and are not yet popped +are popped in the reverse order that they were pushed and then executed. +After all cancellation handlers have been executed, if the thread has any +thread-specific data, appropriate destructor functions are called in an +unspecified order. +Thread termination does not release any application +visible process resources, including, but not limited to, mutexes and +file descriptors, nor does it perform any process level cleanup +actions, including, but not limited to, calling +.Fn atexit +routines that may exist. +.Pp +An implicit call to +.Fn pthread_exit +is made when a thread other than the thread in which +.Fn main +was first invoked returns from the start routine that was used to create +it. +The function's return value serves as the thread's exit status. +.Pp +The behavior of +.Fn pthread_exit +is undefined if called from a cancellation handler or destructor function +that was invoked as the result of an implicit or explicit call to +.Fn pthread_exit . +.Pp +After a thread has terminated, the result of access to local (auto) +variables of the thread is undefined. +Thus, references to local variables +of the exiting thread should not be used for the +.Fn pthread_exit +.Fa value_ptr +parameter value. +.Pp +The process will exit with an exit status of 0 after the last thread has +been terminated. +The behavior is as if the implementation called +.Fn exit +with a zero argument at thread termination time. +.Sh RETURN VALUES +The +.Fn pthread_exit +function cannot return to its caller. +.Sh ERRORS +None. +.Sh SEE ALSO +.Xr _exit 2 , +.Xr exit 3 , +.Xr pthread_cancel 3 , +.Xr pthread_create 3 , +.Xr pthread_join 3 +.Sh STANDARDS +The +.Fn pthread_exit +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_getconcurrency.3 b/static/freebsd/man3/pthread_getconcurrency.3 new file mode 100644 index 00000000..c94e7b9e --- /dev/null +++ b/static/freebsd/man3/pthread_getconcurrency.3 @@ -0,0 +1,113 @@ +.\" Copyright (c) 2003 Sergey Osokin <osa@FreeBSD.org.ru> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.Dd April 11, 2003 +.Dt PTHREAD_GETCONCURRENCY 3 +.Os +.Sh NAME +.Nm pthread_getconcurrency , +.Nm pthread_setconcurrency +.Nd get or set level of concurrency +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_getconcurrency void +.Ft int +.Fn pthread_setconcurrency "int new_level" +.Sh DESCRIPTION +The +.Fn pthread_setconcurrency +function allows an application to inform the threads implementation +of its desired concurrency level, +.Fa new_level . +The actual level of concurrency provided by the implementation +as a result of this function call is unspecified. +If +.Fa new_level +is zero, it causes the implementation to maintain the concurrency +level at its discretion as if +.Fn pthread_setconcurrency +was never called. +The +.Fn pthread_getconcurrency +function returns the value set by a previous call to the +.Fn pthread_setconcurrency +function. +If the +.Fn pthread_setconcurrency +function was not previously called, this function returns zero to +indicate that the implementation is maintaining the concurrency +level. +When an application calls +.Fn pthread_setconcurrency , +it is informing the implementation of its desired concurrency +level. +The implementation uses this as a hint, not a requirement. +.Sh RETURN VALUES +If successful, the +.Fn pthread_setconcurrency +function returns zero. +Otherwise, an error number is returned +to indicate the error. +The +.Fn pthread_getconcurrency +function always returns the concurrency level set by a previous +call to +.Fn pthread_setconcurrency . +If the +.Fn pthread_setconcurrency +function has never been called, +.Fn pthread_getconcurrency +returns zero. +.Sh ERRORS +The +.Fn pthread_setconcurrency +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa new_level +is negative. +.It Bq Er EAGAIN +The value specified by +.Fa new_level +would cause a system resource to be exceeded. +.El +.Sh APPLICATION USAGE +Use of these functions changes the state of the underlying +concurrency upon which the application depends. +Library developers are advised to not use the +.Fn pthread_getconcurrency +and +.Fn pthread_setconcurrency +functions since their use may conflict with an application's +use of these functions. +.Sh STANDARDS +The +.Fn pthread_getconcurrency +and +.Fn pthread_setconcurrency +functions conform to +.St -susv2 . diff --git a/static/freebsd/man3/pthread_getcpuclockid.3 b/static/freebsd/man3/pthread_getcpuclockid.3 new file mode 100644 index 00000000..b372d2df --- /dev/null +++ b/static/freebsd/man3/pthread_getcpuclockid.3 @@ -0,0 +1,84 @@ +.\" Copyright (c) 2012 David Xu <davidxu@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. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.Dd August 21, 2012 +.Dt PTHREAD_GETCPUCLOCKID 3 +.Os +.Sh NAME +.Nm pthread_getcpuclockid +.Nd access a thread CPU-time clock +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.In time.h +.Ft int +.Fn pthread_getcpuclockid "pthread_t thread_id" "clockid_t *clock_id" +.Sh DESCRIPTION +The +.Fn pthread_getcpuclockid +returns the clock ID of the CPU-time clock of the thread specified by +.Fa thread_id , +if the thread described by +.Fa thread_id +exists. +.Sh RETURN VALUES +Upon successful completion, +.Fn pthread_getcpuclockid +returns zero; otherwise, an error number is returned to indicate the +error. +.Sh ERRORS +The +.Fn pthread_getcpuclockid +function will fail if: +.Bl -tag -width Er +.It Bq Er ESRCH +The value specified by +.Fa thread_id +does not refer to an existing thread. +.El +.Sh SEE ALSO +.Xr clock_gettime 2 +.Sh STANDARDS +The +.Fn pthread_getcpuclockid +function conforms to +.St -p1003.1-2004 . +.Sh HISTORY +The +.Fn pthread_getcpuclockid +function first appeared in +.Fx 10.0 . +.Sh AUTHORS +.An David Xu Aq Mt davidxu@FreeBSD.org diff --git a/static/freebsd/man3/pthread_getspecific.3 b/static/freebsd/man3/pthread_getspecific.3 new file mode 100644 index 00000000..c9a46729 --- /dev/null +++ b/static/freebsd/man3/pthread_getspecific.3 @@ -0,0 +1,88 @@ +.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 4, 1996 +.Dt PTHREAD_GETSPECIFIC 3 +.Os +.Sh NAME +.Nm pthread_getspecific +.Nd get a thread-specific data value +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft void * +.Fn pthread_getspecific "pthread_key_t key" +.Sh DESCRIPTION +The +.Fn pthread_getspecific +function returns the value currently bound to the specified +.Fa key +on behalf of the calling thread. +.Pp +The effect of calling +.Fn pthread_getspecific +with a +.Fa key +value not obtained from +.Fn pthread_key_create +or after +.Fa key +has been deleted with +.Fn pthread_key_delete +is undefined. +.Pp +The +.Fn pthread_getspecific +function may be called from a thread-specific data destructor function. +A call to +.Fn pthread_getspecific +for the thread-specific data key being destroyed returns the value NULL, +unless the value is changed (after the destructor starts) by a call to +.Fn pthread_setspecific . +.Sh RETURN VALUES +The +.Fn pthread_getspecific +function will return the thread-specific data value associated with the given +.Fa key . +If no thread-specific data value is associated with +.Fa key , +then the value NULL is returned. +.Sh ERRORS +None. +.Sh SEE ALSO +.Xr pthread_key_create 3 , +.Xr pthread_key_delete 3 , +.Xr pthread_setspecific 3 +.Sh STANDARDS +The +.Fn pthread_getspecific +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_getthreadid_np.3 b/static/freebsd/man3/pthread_getthreadid_np.3 new file mode 100644 index 00000000..da7ae545 --- /dev/null +++ b/static/freebsd/man3/pthread_getthreadid_np.3 @@ -0,0 +1,55 @@ +.\" Copyright (c) 2011 Jung-uk Kim <jkim@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd October 12, 2021 +.Dt PTHREAD_GETTHREADID_NP 3 +.Os +.Sh NAME +.Nm pthread_getthreadid_np +.Nd get the calling thread's integral ID +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft int +.Fn pthread_getthreadid_np void +.Sh DESCRIPTION +The +.Fn pthread_getthreadid_np +function returns the unique integral ID of the calling thread. +Its semantics is similar to the AIX's +.Fn pthread_getthreadid_np +function. +.Sh RETURN VALUES +The +.Fn pthread_getthreadid_np +function returns the thread integral ID of the calling thread. +.Sh ERRORS +None. +.Sh SEE ALSO +.Xr pthread_np 3 , +.Xr pthread_self 3 +.Sh AUTHORS +This manual page was written by +.An Jung-uk Kim Aq Mt jkim@FreeBSD.org . diff --git a/static/freebsd/man3/pthread_join.3 b/static/freebsd/man3/pthread_join.3 new file mode 100644 index 00000000..671ce7bb --- /dev/null +++ b/static/freebsd/man3/pthread_join.3 @@ -0,0 +1,194 @@ +.\" Copyright (c) 1996-1998 John Birrell <jb@cimlogic.com.au>. +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 October 12, 2021 +.Dt PTHREAD_JOIN 3 +.Os +.Sh NAME +.Nm pthread_join , +.Nm pthread_peekjoin_np , +.Nm pthread_timedjoin_np +.Nm pthread_tryjoin_np +.Nd inspect thread termination state +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_join "pthread_t thread" "void **value_ptr" +.In pthread_np.h +.Ft int +.Fo pthread_peekjoin_np +.Fa "pthread_t thread" +.Fa "void **value_ptr" +.Fc +.Ft int +.Fo pthread_timedjoin_np +.Fa "pthread_t thread" +.Fa "void **value_ptr" +.Fa "const struct timespec *abstime" +.Fc +.Ft int +.Fn pthread_tryjoin_np "pthread_t thread" "void **value_ptr" +.Sh DESCRIPTION +The +.Fn pthread_join +function suspends execution of the calling thread until the target +.Fa thread +terminates unless the target +.Fa thread +has already terminated. +.Pp +On return from a successful +.Fn pthread_join +call with a non-NULL +.Fa value_ptr +argument, the value passed to +.Fn pthread_exit +by the terminating thread is stored in the location referenced by +.Fa value_ptr . +When a +.Fn pthread_join +returns successfully, the target thread has been terminated. +The results +of multiple simultaneous calls to +.Fn pthread_join +specifying the same target thread are undefined. +If the thread calling +.Fn pthread_join +is cancelled, then the target thread is not detached. +.Pp +The +.Fn pthread_timedjoin_np +function is equivalent to the +.Fn pthread_join +function except it will return +.Er ETIMEDOUT +if target thread does not exit before specified absolute time passes. +.Pp +The +.Fn pthread_peekjoin_np +only peeks into the exit status of the specified thread. +If the thread has not exited, the +.Er EBUSY +error is returned. +Otherwise, zero is returned and the thread exit value is optionally stored +into the location of +.Fa *value_ptr . +The target thread is left unjoined and can be used as an argument for +the +.Fn pthread_join +family of functions again. +.Pp +The +.Fn pthread_tryjoin_np +function joins the thread if it is already terminated, same as +.Fn pthread_join . +If the thread has not yet terminated, the function returns +.Er EBUSY . +.Pp +A thread that has exited but remains unjoined counts against +[_POSIX_THREAD_THREADS_MAX]. +.Sh RETURN VALUES +If successful, the described functions return zero. +Otherwise an error number is returned to indicate the error or +special condition. +.Sh ERRORS +The +.Fn pthread_join , +.Fn pthread_peekjoin_np , +and +.Fn pthread_timedjoin_np +functions will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The implementation has detected that the value specified by +.Fa thread +does not refer to a joinable thread. +.It Bq Er ESRCH +No thread could be found corresponding to that specified by the given +thread ID, +.Fa thread . +.It Bq Er EDEADLK +A deadlock was detected or the value of +.Fa thread +specifies the calling thread. +.It Bq Er EOPNOTSUPP +The implementation detected that another caller is already waiting on +.Fa thread . +.El +.Pp +Additionally, the +.Fn pthread_timedjoin_np +function will fail if: +.Bl -tag -width Er +.It Bq Er ETIMEDOUT +The specified absolute time passed while +.Fn pthread_timedjoin_np +waited for thread exit. +.El +.Pp +The +.Fn pthread_peekjoin_np +and +.Fn pthread_tryjoin_np +functions will also fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The specified thread has not yet exited. +.El +.Sh SEE ALSO +.Xr wait 2 , +.Xr pthread 3 , +.Xr pthread_create 3 , +.Xr pthread_np 3 +.Sh STANDARDS +The +.Fn pthread_join +function conforms to +.St -p1003.1-96 . +The +.Fn pthread_timedjoin_np +function is a +.Fx +extension which first appeared in +.Fx 6.1 . +The +.Fn pthread_peekjoin_np +function is a +.Fx +extension which first appearead in +.Fx 13.0 . +The +.Fn pthread_tryjoin_np +function is a +.Fx +extension which first appearead in +.Fx 16.0 . diff --git a/static/freebsd/man3/pthread_key_create.3 b/static/freebsd/man3/pthread_key_create.3 new file mode 100644 index 00000000..0faf0a07 --- /dev/null +++ b/static/freebsd/man3/pthread_key_create.3 @@ -0,0 +1,107 @@ +.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 4, 1996 +.Dt PTHREAD_KEY_CREATE 3 +.Os +.Sh NAME +.Nm pthread_key_create +.Nd thread-specific data key creation +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_key_create "pthread_key_t *key" "void (*destructor)(void *)" +.Sh DESCRIPTION +The +.Fn pthread_key_create +function creates a thread-specific data key visible to all threads in the +process. +Key values provided by +.Fn pthread_key_create +are opaque objects used to locate thread-specific data. +Although the same +key value may be used by different threads, the values bound to the key +by +.Fn pthread_setspecific +are maintained on a per-thread basis and persist for the life of the calling +thread. +.Pp +Upon key creation, the value NULL is associated with the new key in all +active threads. +Upon thread creation, the value NULL is associated with all +defined keys in the new thread. +.Pp +An optional destructor function may be associated with each key value. +At +thread exit, if a key value has a non-NULL destructor pointer, and the +thread has a non-NULL value associated with the key, the function pointed +to is called with the current associated value as its sole argument. +The +order of destructor calls is unspecified if more than one destructor exists +for a thread when it exits. +.Pp +If, after all the destructors have been called for all non-NULL values +with associated destructors, there are still some non-NULL values with +associated destructors, then the process is repeated. +If, after at least +[PTHREAD_DESTRUCTOR_ITERATIONS] iterations of destructor calls for +outstanding non-NULL values, there are still some non-NULL values with +associated destructors, the implementation stops calling destructors. +.Sh RETURN VALUES +If successful, the +.Fn pthread_key_create +function will store the newly created key value at the location specified by +.Fa key +and returns zero. +Otherwise an error number will be returned to indicate +the error. +.Sh ERRORS +The +.Fn pthread_key_create +function will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system lacked the necessary resources to create another thread-specific +data key, or the system-imposed limit on the total number of keys per process +[PTHREAD_KEYS_MAX] would be exceeded. +.It Bq Er ENOMEM +Insufficient memory exists to create the key. +.El +.Sh SEE ALSO +.Xr pthread_getspecific 3 , +.Xr pthread_key_delete 3 , +.Xr pthread_setspecific 3 +.Sh STANDARDS +The +.Fn pthread_key_create +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_key_delete.3 b/static/freebsd/man3/pthread_key_delete.3 new file mode 100644 index 00000000..884b261c --- /dev/null +++ b/static/freebsd/man3/pthread_key_delete.3 @@ -0,0 +1,98 @@ +.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 4, 1996 +.Dt PTHREAD_KEY_DELETE 3 +.Os +.Sh NAME +.Nm pthread_key_delete +.Nd delete a thread-specific data key +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_key_delete "pthread_key_t key" +.Sh DESCRIPTION +The +.Fn pthread_key_delete +function deletes a thread-specific data key previously returned by +.Fn pthread_key_create . +The thread-specific data values associated with +.Fa key +need not be NULL at the time that +.Fn pthread_key_delete +is called. +It is the responsibility of the application to free any +application storage or perform any cleanup actions for data structures +related to the deleted key or associated thread-specific data in any threads; +this cleanup can be done either before or after +.Fn pthread_key_delete +is called. +Any attempt to use +.Fa key +following the call to +.Fn pthread_key_delete +results in undefined behavior. +.Pp +The +.Fn pthread_key_delete +function is callable from within destructor functions. +Destructor functions +are not invoked by +.Fn pthread_key_delete . +Any destructor function that may have been associated with +.Fa key +will no longer be called upon thread exit. +.Sh RETURN VALUES +If successful, the +.Fn pthread_key_delete +function will return zero. +Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_key_delete +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa key +value is invalid. +.El +.Sh SEE ALSO +.Xr pthread_getspecific 3 , +.Xr pthread_key_create 3 , +.Xr pthread_setspecific 3 +.Sh STANDARDS +The +.Fn pthread_key_delete +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_kill.3 b/static/freebsd/man3/pthread_kill.3 new file mode 100644 index 00000000..cb2d76c6 --- /dev/null +++ b/static/freebsd/man3/pthread_kill.3 @@ -0,0 +1,75 @@ +.\" Copyright (C) 2000 Jason Evans <jasone@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(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 27, 2000 +.Dt PTHREAD_KILL 3 +.Os +.Sh NAME +.Nm pthread_kill +.Nd send a signal to a specified thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.In signal.h +.Ft int +.Fn pthread_kill "pthread_t thread" "int sig" +.Sh DESCRIPTION +The +.Fn pthread_kill +function sends 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. +.Sh RETURN VALUES +If successful, +.Fn pthread_kill +returns 0. +Otherwise, an error number is returned. +.Sh ERRORS +The +.Fn pthread_kill +function will fail if: +.Bl -tag -width Er +.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 kill 2 , +.Xr pthread_self 3 , +.Xr raise 3 +.Sh STANDARDS +The +.Fn pthread_kill +function conforms to +.St -p1003.1-96 diff --git a/static/freebsd/man3/pthread_main_np.3 b/static/freebsd/man3/pthread_main_np.3 new file mode 100644 index 00000000..58e3b11d --- /dev/null +++ b/static/freebsd/man3/pthread_main_np.3 @@ -0,0 +1,59 @@ +.\" 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. +.\" +.Dd October 12, 2021 +.Dt PTHREAD_MAIN_NP 3 +.Os +.Sh NAME +.Nm pthread_main_np +.Nd identify the initial thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft int +.Fn pthread_main_np void +.Sh DESCRIPTION +The +.Fn pthread_main_np +function +is used in userland threads environment to identify the initial thread. +Its semantics is similar to the Solaris's +.Fn thr_main +function. +.Sh RETURN VALUES +The +.Fn pthread_main_np +function returns +1 if the calling thread is the initial thread, +0 if the calling thread is not the initial thread, +and \-1 if the thread's initialization has not yet completed. +.Sh SEE ALSO +.Xr pthread_create 3 , +.Xr pthread_equal 3 , +.Xr pthread_np 3 , +.Xr pthread_self 3 +.Sh AUTHORS +This manual page was written by +.An Alexey Zelkin Aq Mt phantom@FreeBSD.org . diff --git a/static/freebsd/man3/pthread_multi_np.3 b/static/freebsd/man3/pthread_multi_np.3 new file mode 100644 index 00000000..62c4fb45 --- /dev/null +++ b/static/freebsd/man3/pthread_multi_np.3 @@ -0,0 +1,65 @@ +.\" 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. +.\" +.Dd October 12, 2021 +.Dt PTHREAD_MULTI_NP 3 +.Os +.Sh NAME +.Nm pthread_multi_np , +.Nm pthread_single_np +.Nd "switch between multi- and single-threaded scheduling modes" +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft int +.Fn pthread_multi_np void +.Ft int +.Fn pthread_single_np void +.Sh DESCRIPTION +The +.Fn pthread_single_np +function switches the process to a single-threaded mode, i.e., +suspends all threads except the current. +The semantics of this function is similar to +.Xr pthread_suspend_all_np 3 . +.Pp +The +.Fn pthread_multi_np +function switches the process to a multi-threaded mode. +The semantics of this function is similar to +.Xr pthread_resume_all_np 3 . +.Sh RETURN VALUES +The +.Fn pthread_multi_np +and +.Nm pthread_single_np +functions always return 0. +.Sh SEE ALSO +.Xr pthread_np 3 , +.Xr pthread_resume_all_np 3 , +.Xr pthread_suspend_all_np 3 +.Sh AUTHORS +This manual page was written by +.An Alexey Zelkin Aq Mt phantom@FreeBSD.org . diff --git a/static/freebsd/man3/pthread_mutex_consistent.3 b/static/freebsd/man3/pthread_mutex_consistent.3 new file mode 100644 index 00000000..e22be52b --- /dev/null +++ b/static/freebsd/man3/pthread_mutex_consistent.3 @@ -0,0 +1,91 @@ +.\" Copyright (c) 2016 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, 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 AUTHORS 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 AUTHORS 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 March 27, 2017 +.Dt PTHREAD_MUTEX_CONSISTENT 3 +.Os +.Sh NAME +.Nm pthread_mutex_consistent +.Nd mark state protected by robust mutex as consistent +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_mutex_consistent "pthread_mutex_t *mutex" +.Sh DESCRIPTION +If the process containing the thread owning a robust mutex terminates +while holding the mutex, the mutex becomes inconsistent and the next thread +that acquires the mutex lock is notified of the state by the return value +.Er EOWNERDEAD . +In this case, the mutex does not become normally usable again until +the state is marked consistent. +.Pp +The +.Fn pthread_mutex_consistent , +when called with the +.Fa mutex +argument, which points to the initialized robust mutex in an +inconsistent state, marks the by mutex as consistent again. +The consequent unlock of the mutex, by either +.Fn pthread_mutex_unlock +or other methods, allows other contenders to lock the mutex. +.Pp +If the mutex in the inconsistent state is not marked consistent +by the call to +.Fn pthread_mutex_consistent +before unlock, +further attempts to lock the +.Fa mutex +result in the +.Er ENOTRECOVERABLE +condition reported by the locking functions. +.Sh RETURN VALUES +If successful, +.Fn pthread_mutex_consistent +will return zero, otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_mutex_lock +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The mutex pointed to by the +.Fa mutex +argument is not robust, or is not in the inconsistent state. +.El +.Sh SEE ALSO +.Xr pthread_mutex_init 3 , +.Xr pthread_mutex_lock 3 , +.Xr pthread_mutex_unlock 3 , +.Xr pthread_mutexattr_setrobust 3 +.Sh STANDARDS +The +.Fn pthread_mutex_lock +function conforms to +.St -susv4 . diff --git a/static/freebsd/man3/pthread_mutex_destroy.3 b/static/freebsd/man3/pthread_mutex_destroy.3 new file mode 100644 index 00000000..3627a6c8 --- /dev/null +++ b/static/freebsd/man3/pthread_mutex_destroy.3 @@ -0,0 +1,72 @@ +.\" Copyright (c) 1997 Brian Cully <shmit@kublai.com> +.\" 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 author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 July 29, 1998 +.Dt PTHREAD_MUTEX_DESTROY 3 +.Os +.Sh NAME +.Nm pthread_mutex_destroy +.Nd free resources allocated for a mutex +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_mutex_destroy "pthread_mutex_t *mutex" +.Sh DESCRIPTION +The +.Fn pthread_mutex_destroy +function frees the resources allocated for +.Fa mutex . +.Sh RETURN VALUES +If successful, +.Fn pthread_mutex_destroy +will return zero, otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_mutex_destroy +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa mutex +is invalid. +.It Bq Er EBUSY +.Fa Mutex +is locked by another thread. +.El +.Sh SEE ALSO +.Xr pthread_mutex_init 3 , +.Xr pthread_mutex_lock 3 , +.Xr pthread_mutex_trylock 3 , +.Xr pthread_mutex_unlock 3 +.Sh STANDARDS +The +.Fn pthread_mutex_destroy +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_mutex_init.3 b/static/freebsd/man3/pthread_mutex_init.3 new file mode 100644 index 00000000..4133cf07 --- /dev/null +++ b/static/freebsd/man3/pthread_mutex_init.3 @@ -0,0 +1,76 @@ +.\" Copyright (c) 1997 Brian Cully <shmit@kublai.com> +.\" 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 author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 August 17, 2018 +.Dt PTHREAD_MUTEX_INIT 3 +.Os +.Sh NAME +.Nm pthread_mutex_init +.Nd create a mutex +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_mutex_init "pthread_mutex_t *restrict mutex" "const pthread_mutexattr_t *restrict attr" +.Sh DESCRIPTION +The +.Fn pthread_mutex_init +function creates a new mutex, with attributes specified with +.Fa attr . +If +.Fa attr +is NULL the default attributes are used. +.Sh RETURN VALUES +If successful, +.Fn pthread_mutex_init +will return zero and put the new mutex id into +.Fa mutex , +otherwise an error number will be returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_mutex_init +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.It Bq Er ENOMEM +The process cannot allocate enough memory to create another mutex. +.El +.Sh SEE ALSO +.Xr pthread_mutex_destroy 3 , +.Xr pthread_mutex_lock 3 , +.Xr pthread_mutex_trylock 3 , +.Xr pthread_mutex_unlock 3 , +.Xr pthread_mutexattr 3 +.Sh STANDARDS +The +.Fn pthread_mutex_init +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_mutex_lock.3 b/static/freebsd/man3/pthread_mutex_lock.3 new file mode 100644 index 00000000..ba54cd45 --- /dev/null +++ b/static/freebsd/man3/pthread_mutex_lock.3 @@ -0,0 +1,86 @@ +.\" Copyright (c) 1997 Brian Cully <shmit@kublai.com> +.\" 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 author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 August 7, 2019 +.Dt PTHREAD_MUTEX_LOCK 3 +.Os +.Sh NAME +.Nm pthread_mutex_lock +.Nd lock a mutex +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_mutex_lock "pthread_mutex_t *mutex" +.Sh DESCRIPTION +The +.Fn pthread_mutex_lock +function locks +.Fa mutex . +If the mutex is already locked, the calling thread will block until the +mutex becomes available. +.Sh RETURN VALUES +If successful, +.Fn pthread_mutex_lock +will return zero, otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_mutex_lock +function will fail if: +.Bl -tag -width "Er ENOTRECOVERABLE" +.It Bq Er EINVAL +The value specified by +.Fa mutex +is invalid. +.It Bq Er EDEADLK +A deadlock would occur if the thread blocked waiting for +.Fa mutex . +.It Bq Er EOWNERDEAD +The argument +.Fa mutex +points to a robust mutex and the process containing the previous owning +thread terminated while holding the mutex lock. +The lock was granted to the caller and it is up to the new owner +to make the state consistent. +.It Bq Er ENOTRECOVERABLE +The state protected by the +.Fa mutex +is not recoverable. +.El +.Sh SEE ALSO +.Xr pthread_mutex_consistent 3 , +.Xr pthread_mutex_destroy 3 , +.Xr pthread_mutex_init 3 , +.Xr pthread_mutex_trylock 3 , +.Xr pthread_mutex_unlock 3 +.Sh STANDARDS +The +.Fn pthread_mutex_lock +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_mutex_timedlock.3 b/static/freebsd/man3/pthread_mutex_timedlock.3 new file mode 100644 index 00000000..b6e95edb --- /dev/null +++ b/static/freebsd/man3/pthread_mutex_timedlock.3 @@ -0,0 +1,113 @@ +.\" Copyright (c) 2003 Michael Telahun Makonnen +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 7, 2019 +.Dt PTHREAD_MUTEX_TIMEDLOCK 3 +.Os +.Sh NAME +.Nm pthread_mutex_timedlock +.Nd lock a mutex without blocking indefinitely +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.In time.h +.Ft int +.Fn pthread_mutex_timedlock "pthread_mutex_t *restrict mutex" "const struct timespec *restrict abs_timeout" +.Sh DESCRIPTION +The +.Fn pthread_mutex_timedlock +function will lock +.Fa mutex . +If it is already locked the calling thread will block until +the mutex becomes available or +the timeout, +specified by abs_timeout, +expires. +The time of the timeout is an absolute time and +is not relative to the current time. +.Sh RETURN VALUES +If successful, +.Fn pthread_mutex_timedlock +will return zero, otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_mutex_timedlock +function will fail if: +.Bl -tag -width Er +.It Bq "Er ENOTRECOVERABLE" +The +.Fa mutex +was created with the protocol attribute having the +value PTHREAD_PRIO_PROTECT and +the calling thread's priority is higher than the +mutex's current priority ceiling. +.It Bq Er EINVAL +The process or thread would have blocked, and +.Fa abs_timeout +specified a nanosecond value less than zero or +greater than or equal to 1 billion. +.It Bq Er EINVAL +The +.Fa mutex +parameter is invalid. +.It Bq Er ETIMEDOUT +The +.Fa mutex +could not be locked before the timeout expired. +.It Bq Er EAGAIN +The +.Fa mutex +could not be acquired because the +maximum number of recursive locks for the +.Fa mutex +has been exceeded. +.It Bq Er EDEADLK +The current thread already owns the +.Fa mutex . +.It Bq Er EOWNERDEAD +The argument +.Fa mutex +points to a robust mutex and the process containing the previous owning +thread terminated while holding the mutex lock. +The lock was granted to the caller and it is up to the new owner +to make the state consistent. +.It Bq Er ENOTRECOVERABLE +The state protected by the +.Fa mutex +is not recoverable. +.El +.Sh SEE ALSO +.Xr pthread_mutex_consistent 3 , +.Xr pthread_mutex_destroy 3 , +.Xr pthread_mutex_init 3 , +.Xr pthread_mutex_lock 3 , +.Xr pthread_mutex_trylock 3 , +.Xr pthread_mutex_unlock 3 +.Sh STANDARDS +The +.Fn pthread_mutex_timedlock +function is expected to conform to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_mutex_trylock.3 b/static/freebsd/man3/pthread_mutex_trylock.3 new file mode 100644 index 00000000..cd08d760 --- /dev/null +++ b/static/freebsd/man3/pthread_mutex_trylock.3 @@ -0,0 +1,87 @@ +.\" Copyright (c) 1997 Brian Cully <shmit@kublai.com> +.\" 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 author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 August 7, 2019 +.Dt PTHREAD_MUTEX_TRYLOCK 3 +.Os +.Sh NAME +.Nm pthread_mutex_trylock +.Nd attempt to lock a mutex without blocking +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_mutex_trylock "pthread_mutex_t *mutex" +.Sh DESCRIPTION +The +.Fn pthread_mutex_trylock +function locks +.Fa mutex . +If the mutex is already locked, +.Fn pthread_mutex_trylock +will not block waiting for the mutex, but will return an error condition. +.Sh RETURN VALUES +If successful, +.Fn pthread_mutex_trylock +will return zero, otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_mutex_trylock +function will fail if: +.Bl -tag -width "Er ENOTRECOVERABLE" +.It Bq Er EINVAL +The value specified by +.Fa mutex +is invalid. +.It Bq Er EBUSY +.Fa Mutex +is already locked. +.It Bq Er EOWNERDEAD +The argument +.Fa mutex +points to a robust mutex and the process containing the previous owning +thread terminated while holding the mutex lock. +The lock was granted to the caller and it is up to the new owner +to make the state consistent. +.It Bq Er ENOTRECOVERABLE +The state protected by the +.Fa mutex +is not recoverable. +.El +.Sh SEE ALSO +.Xr pthread_mutex_consistent 3 , +.Xr pthread_mutex_destroy 3 , +.Xr pthread_mutex_init 3 , +.Xr pthread_mutex_lock 3 , +.Xr pthread_mutex_unlock 3 +.Sh STANDARDS +The +.Fn pthread_mutex_trylock +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_mutex_unlock.3 b/static/freebsd/man3/pthread_mutex_unlock.3 new file mode 100644 index 00000000..eb6866a2 --- /dev/null +++ b/static/freebsd/man3/pthread_mutex_unlock.3 @@ -0,0 +1,85 @@ +.\" Copyright (c) 1997 Brian Cully <shmit@kublai.com> +.\" 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 author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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, 2016 +.Dt PTHREAD_MUTEX_UNLOCK 3 +.Os +.Sh NAME +.Nm pthread_mutex_unlock +.Nd unlock a mutex +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_mutex_unlock "pthread_mutex_t *mutex" +.Sh DESCRIPTION +If the current thread holds the lock on +.Fa mutex , +then the +.Fn pthread_mutex_unlock +function unlocks +.Fa mutex . +.Pp +If the argument pointed by the +.Fa mutex +is a robust mutex in the inconsistent state, and the call to +.Fn pthread_mutex_consistent +function was not done prior to unlocking, further locking attempts on +the mutex +.Fa mutex +are denied and locking functions return +.Er ENOTRECOVERABLE +error. +.Sh RETURN VALUES +If successful, +.Fn pthread_mutex_unlock +will return zero, otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_mutex_unlock +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa mutex +is invalid. +.It Bq Er EPERM +The current thread does not hold a lock on +.Fa mutex . +.El +.Sh SEE ALSO +.Xr pthread_mutex_destroy 3 , +.Xr pthread_mutex_init 3 , +.Xr pthread_mutex_lock 3 , +.Xr pthread_mutex_trylock 3 +.Sh STANDARDS +The +.Fn pthread_mutex_unlock +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_mutexattr.3 b/static/freebsd/man3/pthread_mutexattr.3 new file mode 100644 index 00000000..b18d93e2 --- /dev/null +++ b/static/freebsd/man3/pthread_mutexattr.3 @@ -0,0 +1,368 @@ +.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. +.\" Copyright (c) 2021 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" Part of 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 October 27, 2023 +.Dt PTHREAD_MUTEXATTR 3 +.Os +.Sh NAME +.Nm pthread_mutexattr_init , +.Nm pthread_mutexattr_destroy , +.Nm pthread_mutexattr_setprioceiling , +.Nm pthread_mutexattr_getprioceiling , +.Nm pthread_mutexattr_setprotocol , +.Nm pthread_mutexattr_getprotocol , +.Nm pthread_mutexattr_setpshared , +.Nm pthread_mutexattr_getpshared , +.Nm pthread_mutexattr_setrobust , +.Nm pthread_mutexattr_getrobust , +.Nm pthread_mutexattr_settype , +.Nm pthread_mutexattr_gettype +.Nd mutex attribute operations +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_mutexattr_init "pthread_mutexattr_t *attr" +.Ft int +.Fn pthread_mutexattr_destroy "pthread_mutexattr_t *attr" +.Ft int +.Fo pthread_mutexattr_setprioceiling +.Fa "pthread_mutexattr_t *attr" "int prioceiling" +.Fc +.Ft int +.Fo pthread_mutexattr_getprioceiling +.Fa "const pthread_mutexattr_t *attr" "int *prioceiling" +.Fc +.Ft int +.Fn pthread_mutexattr_setprotocol "pthread_mutexattr_t *attr" "int protocol" +.Ft int +.Fo pthread_mutexattr_getprotocol +.Fa "const pthread_mutexattr_t *restrict attr" "int *restrict protocol" +.Fc +.Ft int +.Fo pthread_mutexattr_setpshared +.Fa "pthread_mutexattr_t *attr" "int shared" +.Fc +.Ft int +.Fo pthread_mutexattr_getpshared +.Fa "const pthread_mutexattr_t *attr" "int *shared" +.Fc +.Ft int +.Fn pthread_mutexattr_setrobust "pthread_mutexattr_t *attr" "int robust" +.Ft int +.Fn pthread_mutexattr_getrobust "pthread_mutexattr_t *attr" "int *robust" +.Ft int +.Fn pthread_mutexattr_settype "pthread_mutexattr_t *attr" "int type" +.Ft int +.Fo pthread_mutexattr_gettype +.Fa "const pthread_mutexattr_t *restrict attr" "int *restrict type" +.Fc +.Sh DESCRIPTION +Mutex attributes are used to specify parameters to +.Fn pthread_mutex_init . +One attribute object can be used in multiple calls to +.Fn pthread_mutex_init , +with or without modifications between calls. +.Pp +The +.Fn pthread_mutexattr_init +function initializes +.Fa attr +with all the default mutex attributes. +.Pp +The +.Fn pthread_mutexattr_destroy +function destroys +.Fa attr . +.Pp +The +.Fn pthread_mutexattr_setprioceiling +function sets the priority ceiling for the mutex, used +by threads executed under the +.Dv PTHREAD_PRIO_PROTECT +protocol. +.Pp +The +.Fn pthread_mutexattr_setprotocol +function specifies the protocol to be followed in utilizing mutexes. +The +.Fa protocol +argument can take one of the following values: +.Bl -tag -width PTHREAD_PRIO_PROTECT +.It PTHREAD_PRIO_NONE +Priority and scheduling of the thread owning this mutex is not +affected by its mutex ownership. +.It PTHREAD_PRIO_INHERIT +Request priority-inheritance protocol, where the thread owning the mutex +is executed at the highest priority among priorities of all threads waiting +on any mutex owned by this thread. +.It PTHREAD_PRIO_PROTECT +Request priority-inheritance protocol, where the thread owning the mutex +is executed at highest priority among priorities or priority ceilings of +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 +.Fa robust +argument are +.Bl -tag -width PTHREAD_MUTEX_STALLED +.It PTHREAD_MUTEX_STALLED +No special actions are taken if the thread owning the mutex is terminated +without unlocking the mutex lock. +This can lead to deadlocks if no other thread can unlock the mutex. +This is the default value. +.It PTHREAD_MUTEX_ROBUST +If the process containing the owning thread of a robust mutex, or owning +thread, terminates while holding the mutex lock, the next thread that +acquires the mutex is notified about the termination +by the return value +.Ev EOWNERDEAD +from the locking function. +Then, either +.Xr pthread_mutex_consistent 3 +can be used to repair the mutex lock state, or +.Xr pthread_mutex_unlock 3 +can unlock the mutex lock but also put it an unusable state, +where all further attempts to acquire it result in the +.Ev ENOTRECOVERABLE +error. +.El +.Pp +The +.Fn pthread_mutexattr_settype +function sets the type of the mutex. +The type affects the behavior of calls which lock and unlock the mutex. +The possible values for the +.Fa type +argument are +.Bl -tag -width PTHREAD_MUTEX_ERRORCHECK +.It PTHREAD_MUTEX_NORMAL +Both recursive locking, and unlocking when the lock is not owned by the current +thread, cause an error to be returned from the corresponding functions. +This matches +.Dv PTHREAD_MUTEX_ERRORCHECK +but somewhat contradicts the behavior mandated by POSIX. +.It PTHREAD_MUTEX_ERRORCHECK +Both recursive locking, and unlocking when the lock is not owned by the current +thread, cause an error returned from the corresponding functions. +.It PTHREAD_MUTEX_RECURSIVE +Recursive locking is allowed. +Attempt to unlock when current thread is not an owner of the lock causes +an error to be returned. +.It PTHREAD_MUTEX_DEFAULT +The +.Fx +implementation maps this type to +.Dv PTHREAD_MUTEX_ERRORCHECK +type. +.El +.Pp +The +.Fn pthread_mutexattr_get* +functions copy the value of the attribute that corresponds to each function name +to the location pointed to by the second function parameter. +.Sh RETURN VALUES +If successful, these functions return 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_mutexattr_init +function will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Out of memory. +.El +.Pp +The +.Fn pthread_mutexattr_destroy +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.El +.Pp +The +.Fn pthread_mutexattr_setprioceiling +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr , +or invalid value for +.Fa prioceiling . +.El +.Pp +The +.Fn pthread_mutexattr_getprioceiling +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.El +.Pp +The +.Fn pthread_mutexattr_setprotocol +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr , +or invalid value for +.Fa protocol . +.El +.Pp +The +.Fn pthread_mutexattr_getprotocol +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.El +.Pp +The +.Fn pthread_mutexattr_setpshared +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr , +or invalid value for +.Fa shared . +.El +.Pp +The +.Fn pthread_mutexattr_getpshared +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.El +.Pp +The +.Fn pthread_mutexattr_settype +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr , +or invalid value for +.Fa type . +.El +.Pp +The +.Fn pthread_mutexattr_gettype +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.El +.Pp +The +.Fn pthread_mutexattr_setrobust +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr , +or invalid value for +.Fa robust . +.El +.Pp +The +.Fn pthread_mutexattr_getrobust +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Invalid value for +.Fa attr . +.El +.Sh SEE ALSO +.Xr libthr 3 , +.Xr pthread_mutex_init 3 +.Sh STANDARDS +The +.Fn pthread_mutexattr_init +and +.Fn pthread_mutexattr_destroy +functions conform to +.St -p1003.1-96 +.Pp +The +.Fn pthread_mutexattr_setprioceiling , +.Fn pthread_mutexattr_getprioceiling , +.Fn pthread_mutexattr_setprotocol , +.Fn pthread_mutexattr_getprotocol , +.Fn pthread_mutexattr_setpshared , +.Fn pthread_mutexattr_getpshared , +.Fn pthread_mutexattr_settype , +and +.Fn pthread_mutexattr_gettype +functions conform to +.St -susv2 . +The +.Fn pthread_mutexattr_setrobust +and +.Fn pthread_mutexattr_getrobust +functions conform to +.St -susv4 . diff --git a/static/freebsd/man3/pthread_mutexattr_getkind_np.3 b/static/freebsd/man3/pthread_mutexattr_getkind_np.3 new file mode 100644 index 00000000..15eb7061 --- /dev/null +++ b/static/freebsd/man3/pthread_mutexattr_getkind_np.3 @@ -0,0 +1,80 @@ +.\" 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. +.\" +.Dd October 12, 2021 +.Dt PTHREAD_MUTEXATTR_GETKIND_NP 3 +.Os +.Sh NAME +.Nm pthread_mutexattr_getkind_np , +.Nm pthread_mutexattr_setkind_np +.Nd mutex attribute operations (legacy) +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft int +.Fn pthread_mutexattr_getkind_np "pthread_mutexattr_t attr" +.Ft int +.Fn pthread_mutexattr_setkind_np "pthread_mutexattr_t *attr" "int kind" +.Sh DESCRIPTION +.Bf -symbolic +These functions are deprecated and non-portable implementation of +the mutex type manipulation. +.Ef +.Pp +It is recommended to use the +.Xr pthread_mutexattr_gettype 3 +and +.Xr pthread_mutexattr_settype 3 +functions instead. +.Sh RETURN VALUES +The +.Fn pthread_mutexattr_getkind_np +function returns a positive value representing the +.Dq kind +of the mutex attribute +.Fa attr +if successful; otherwise the value \-1 is returned and the global variable +.Va errno +is set to indicate the error. +.Pp +.Rv -std pthread_mutexattr_setkind_np +.Sh ERRORS +The +.Fn pthread_mutexattr_getkind_np +and +.Fn pthread_mutexattr_setkind_np +functions will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_mutex_destroy 3 , +.Xr pthread_mutex_init 3 , +.Xr pthread_mutexattr_gettype 3 , +.Xr pthread_mutexattr_settype 3 , +.Xr pthread_np 3 diff --git a/static/freebsd/man3/pthread_np.3 b/static/freebsd/man3/pthread_np.3 new file mode 100644 index 00000000..c6f0efac --- /dev/null +++ b/static/freebsd/man3/pthread_np.3 @@ -0,0 +1,226 @@ +.\" Copyright (c) 2021 Felix Johnson <felix.the.red@gmail.com> +.\" +.\" 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 COPYRIGHT HOLDERS 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 COPYRIGHT +.\" HOLDER 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 October 12, 2021 +.Dt PTHREAD_NP 3 +.Os +.Sh NAME +.Nm pthread_np +.Nd FreeBSD extensions to POSIX thread functions +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Sh DESCRIPTION +This manual page documents extensions to the POSIX thread functions. +These extensions may or may not be portable to other operating systems. +.Pp +The POSIX thread functions are summarized in this section in the following +groups: +.Pp +.Bl -bullet -offset indent -compact +.It +Thread Routines +.It +Attribute Object Routines +.It +Mutex Routines +.El +.\" .It +.\" Condition Variable Routines +.\" .It +.\" Read/Write Lock Routines +.\" .It +.\" Per-Thread Context Routines +.\" .It +.\" Cleanup Routines +.Ss Thread Routines +.Bl -tag -width indent +.It Xo +.Ft int +.Fo pthread_getaffinity_np +.Fa "pthread_t td" "size_t cpusetsize" "cpuset_t *cpusetp" +.Fc +.Xc +Get the CPU affinity of a specified thread. +.It Xo +.Ft int +.Fn pthread_get_name_np "pthread_t thread" "char *name" "size_t len" +.Xc +Get the name of a specified thread. +.It Xo +.Ft int +.Fn pthread_getname_np "pthread_t thread" "char *name" "size_t len" +.Xc +Get the name of a specified thread. +.It Xo +.Ft int +.Fn pthread_getthreadid_np void +.Xc +Get the calling thread's integral ID. +.It Xo +.Ft int +.Fn pthread_main_np void +.Xc +Identify the initial thread. +.It Xo +.Ft int +.Fn pthread_multi_np void +.Xc +Sets the thread's scheduling mode to multi-threaded. +.It Xo +.Ft int +.Fn pthread_peekjoin_np "pthread_t thread" "void **value_ptr" +.Xc +Peek into the exit status of a specified thread. +.It Xo +.Ft int +.Fn pthread_resume_all_np void +.Xc +Resume all suspended threads. +.It Xo +.Ft int +.Fo pthread_setaffinity_np +.Fa "pthread_t td" "size_t cpusetsize" "const cpuset_t *cpusetp" +.Fc +.Xc +Set the CPU affinity of a specified thread. +.It Xo +.Ft int +.Fn pthread_set_name_np "pthread_t thread" "char *name" +.Xc +Sets the specified thread's name. +.It Xo +.Ft int +.Fn pthread_setname_np "pthread_t thread" "char *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 +Sets the thread's scheduling mode to single-threaded. +.It Xo +.Ft int +.Fn pthread_suspend_np "pthread_t tid" +.Xc +Suspend the specified thread. +.It Xo +.Ft int +.Fn pthread_suspend_all_np void +.Xc +Suspend all active threads. +.It Xo +.Ft int +.Fo pthread_timedjoin_np +.Fa "pthread_t thread" "void **value_ptr" "const struct timespec *abstime" +.Fc +.Xc +A variant of +.Fn pthread_join +with a timeout. +.El +.Ss Attribute Object Routines +.Bl -tag -width indent +.It Xo +.Ft int +.Fo pthread_attr_get_np +.Fa "pthread_t pid" "pthread_attr_t *dst" +.Fc +.Xc +Get the attributes of an existent thread. +.It Xo +.Ft int +.Fo pthread_attr_getaffinity_np +.Fa "const pthread_attr_t *pattr" "size_t cpusetsize" "cpuset_t *cpusetp" +.Fc +.Xc +Get the CPU affinity mask from the thread attribute object. +.It Xo +.Ft int +.Fo pthread_attr_setaffinity_np +.Fa "pthread_attr_t *pattr" "size_t cpusetsize" "const cpuset_t *cpusetp" +.Fc +.Xc +Set the CPU affinity mask for the thread attribute object. +.It Xo +.Ft int +.Fn pthread_attr_setcreatesuspend_np "pthread_attr_t *attr" +.Xc +Permit creation of suspended threads. +.El +.Ss Mutex Routines +.Bl -tag -width indent +.It Xo +.Ft int +.Fn pthread_mutexattr_getkind_np "pthread_mutexattr_t attr" +.Xc +Deprecated, use +.Xr pthread_mutexattr_gettype 3 +instead. +.It Xo +.Ft int +.Fn pthread_mutexattr_setkind_np "pthread_mutexattr_t *attr" +.Xc +Deprecated, use +.Xr pthread_mutexattr_settype 3 +instead. +.El +.\" .Ss Condition Variable Routines +.\" .Bl -tag -width indent +.\" .El +.\" .Ss Read/Write Lock Routines +.\" .Bl -tag -width indent +.\" .El +.\" .Ss Per-Thread Context Routines +.\" .Bl -tag -width indent +.\" .El +.\" .Ss Cleanup Routines +.\" .Bl -tag -width indent +.\" .El +.Sh SEE ALSO +.Xr libthr 3 , +.Xr pthread 3 , +.Xr pthread_affinity_np 3 , +.Xr pthread_attr_affinity_np 3 , +.Xr pthread_attr_get_np 3 , +.Xr pthread_attr_setcreatesuspend_np 3 , +.Xr pthread_getthreadid_np 3 , +.Xr pthread_join 3 , +.Xr pthread_main_np 3 , +.Xr pthread_multi_np 3 , +.Xr pthread_mutexattr_getkind_np 3 , +.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 +.Sh STANDARDS +All of these functions are non-portable extensions to POSIX threads. diff --git a/static/freebsd/man3/pthread_once.3 b/static/freebsd/man3/pthread_once.3 new file mode 100644 index 00000000..1ff0a74b --- /dev/null +++ b/static/freebsd/man3/pthread_once.3 @@ -0,0 +1,105 @@ +.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 4, 1996 +.Dt PTHREAD_ONCE 3 +.Os +.Sh NAME +.Nm pthread_once +.Nd dynamic package initialization +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Pp +pthread_once_t +.Fa once_control += PTHREAD_ONCE_INIT; +.Ft int +.Fn pthread_once "pthread_once_t *once_control" "void (*init_routine)(void)" +.Sh DESCRIPTION +The first call to +.Fn pthread_once +by any thread in a process, with a given +.Fa once_control , +will call the +.Fn init_routine +with no arguments. +Subsequent calls to +.Fn pthread_once +with the same +.Fa once_control +will not call the +.Fn init_routine . +On return from +.Fn pthread_once , +it is guaranteed that +.Fn init_routine +has completed. +The +.Fa once_control +parameter is used to determine whether the associated initialization +routine has been called. +.Pp +The function +.Fn pthread_once +is not a cancellation point. +However, if +.Fn init_routine +is a cancellation point and is cancelled, the effect on +.Fa once_control +is as if +.Fn pthread_once +was never called. +.Pp +The constant +.Fa PTHREAD_ONCE_INIT +is defined by header +.In pthread.h . +.Pp +The behavior of +.Fn pthread_once +is undefined if +.Fa once_control +has automatic storage duration or is not initialized by +.Fa PTHREAD_ONCE_INIT . +.Sh RETURN VALUES +If successful, the +.Fn pthread_once +function will return zero. +Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +None. +.Sh STANDARDS +The +.Fn pthread_once +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_resume_all_np.3 b/static/freebsd/man3/pthread_resume_all_np.3 new file mode 100644 index 00000000..411d5a57 --- /dev/null +++ b/static/freebsd/man3/pthread_resume_all_np.3 @@ -0,0 +1,50 @@ +.\" 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. +.\" +.Dd October 12, 2021 +.Dt PTHREAD_RESUME_ALL_NP 3 +.Os +.Sh NAME +.Nm pthread_resume_all_np +.Nd resume all suspended threads +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft void +.Fn pthread_resume_all_np void +.Sh DESCRIPTION +The +.Fn pthread_resume_all_np +function causes all active threads to be scanned +and resumes those which were previously suspended. +.Sh SEE ALSO +.Xr pthread_attr_setcreatesuspend_np 3 , +.Xr pthread_np 3 , +.Xr pthread_resume_np 3 , +.Xr pthread_suspend_all_np 3 , +.Xr pthread_suspend_np 3 +.Sh AUTHORS +This manual page was written by +.An Alexey Zelkin Aq Mt phantom@FreeBSD.org . diff --git a/static/freebsd/man3/pthread_resume_np.3 b/static/freebsd/man3/pthread_resume_np.3 new file mode 100644 index 00000000..546e1336 --- /dev/null +++ b/static/freebsd/man3/pthread_resume_np.3 @@ -0,0 +1,71 @@ +.\" 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. +.\" +.Dd October 12, 2021 +.Dt PTHREAD_RESUME_NP 3 +.Os +.Sh NAME +.Nm pthread_resume_np +.Nd resume suspended thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft int +.Fn pthread_resume_np "pthread_t tid" +.Sh DESCRIPTION +The +.Fn pthread_resume_np +function, called on a suspended thread, causes it to resume. +If a thread specified by the +.Fa tid +argument is not suspended, no actions will be performed. +.Sh RETURN VALUES +If successful, +.Fn pthread_resume_np +function returns 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_resume_np +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by the +.Fa tid +argument is invalid. +.It Bq Er ESRCH +No thread could be found corresponding to the thread ID specified by the +.Fa tid +argument. +.El +.Sh SEE ALSO +.Xr pthread_attr_setcreatesuspend_np 3 , +.Xr pthread_np 3 , +.Xr pthread_resume_all_np 3 , +.Xr pthread_suspend_all_np 3 , +.Xr pthread_suspend_np 3 +.Sh AUTHORS +This manual page was written by +.An Alexey Zelkin Aq Mt phantom@FreeBSD.org . diff --git a/static/freebsd/man3/pthread_rwlock_destroy.3 b/static/freebsd/man3/pthread_rwlock_destroy.3 new file mode 100644 index 00000000..9c50e71f --- /dev/null +++ b/static/freebsd/man3/pthread_rwlock_destroy.3 @@ -0,0 +1,81 @@ +.\" Copyright (c) 1998 Alex Nash +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 4, 1998 +.Dt PTHREAD_RWLOCK_DESTROY 3 +.Os +.Sh NAME +.Nm pthread_rwlock_destroy +.Nd destroy a read/write lock +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_rwlock_destroy "pthread_rwlock_t *lock" +.Sh DESCRIPTION +The +.Fn pthread_rwlock_destroy +function is used to destroy a read/write lock previously created with +.Fn pthread_rwlock_init . +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlock_destroy +function will return zero. +Otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_rwlock_destroy +function will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +The caller does not have the privilege to perform the operation. +.El +.Pp +The +.Fn pthread_rwlock_destroy +function may fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The system has detected an attempt to destroy the object referenced by +.Fa lock +while it is locked. +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_rwlock_init 3 +.Sh STANDARDS +The +.Fn pthread_rwlock_destroy +function is expected to conform to +.St -susv2 . +.Sh HISTORY +The +.Fn pthread_rwlock_destroy +function first appeared in +.Fx 3.0 . diff --git a/static/freebsd/man3/pthread_rwlock_init.3 b/static/freebsd/man3/pthread_rwlock_init.3 new file mode 100644 index 00000000..e6474199 --- /dev/null +++ b/static/freebsd/man3/pthread_rwlock_init.3 @@ -0,0 +1,98 @@ +.\" Copyright (c) 1998 Alex Nash +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 17, 2018 +.Dt PTHREAD_RWLOCK_INIT 3 +.Os +.Sh NAME +.Nm pthread_rwlock_init +.Nd initialize a read/write lock +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_rwlock_init "pthread_rwlock_t *restrict lock" "const pthread_rwlockattr_t *restrict attr" +.Sh DESCRIPTION +The +.Fn pthread_rwlock_init +function is used to initialize a read/write lock, with attributes +specified by +.Fa attr . +If +.Fa attr +is NULL, the default read/write lock attributes are used. +.Pp +The results of calling +.Fn pthread_rwlock_init +with an already initialized lock are undefined. +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlock_init +function will return zero. +Otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_rwlock_init +function will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system lacked the necessary resources (other than memory) to +initialize the lock. +.It Bq Er ENOMEM +Insufficient memory exists to initialize the lock. +.It Bq Er EPERM +The caller does not have sufficient privilege to perform the +operation. +.El +.Pp +The +.Fn pthread_rwlock_init +function may fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The system has detected an attempt to re-initialize the object +referenced by +.Fa lock , +a previously initialized but not yet destroyed read/write lock. +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_rwlock_destroy 3 , +.Xr pthread_rwlockattr_init 3 , +.Xr pthread_rwlockattr_setpshared 3 +.Sh STANDARDS +The +.Fn pthread_rwlock_init +function is expected to conform to +.St -susv2 . +.Sh HISTORY +The +.Fn pthread_rwlock_init +function first appeared in +.Fx 3.0 . diff --git a/static/freebsd/man3/pthread_rwlock_rdlock.3 b/static/freebsd/man3/pthread_rwlock_rdlock.3 new file mode 100644 index 00000000..f8403fc8 --- /dev/null +++ b/static/freebsd/man3/pthread_rwlock_rdlock.3 @@ -0,0 +1,125 @@ +.\" Copyright (c) 1998 Alex Nash +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 4, 1998 +.Dt PTHREAD_RWLOCK_RDLOCK 3 +.Os +.Sh NAME +.Nm pthread_rwlock_rdlock , +.Nm pthread_rwlock_tryrdlock +.Nd acquire a read/write lock for reading +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_rwlock_rdlock "pthread_rwlock_t *lock" +.Ft int +.Fn pthread_rwlock_tryrdlock "pthread_rwlock_t *lock" +.Sh DESCRIPTION +The +.Fn pthread_rwlock_rdlock +function acquires a read lock on +.Fa lock +provided that +.Fa lock +is not presently held for writing and no writer threads are +presently blocked on the lock. +If the read lock cannot be +immediately acquired, the calling thread blocks until it can +acquire the lock. +.Pp +The +.Fn pthread_rwlock_tryrdlock +function performs the same action, but does not block if the lock +cannot be immediately obtained (i.e., the lock is held for writing +or there are waiting writers). +.Pp +A thread may hold multiple concurrent read locks. +If so, +.Fn pthread_rwlock_unlock +must be called once for each lock obtained. +.Pp +The results of acquiring a read lock while the calling thread holds +a write lock are undefined. +.Sh IMPLEMENTATION NOTES +To prevent writer starvation, writers are favored over readers. +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlock_rdlock +and +.Fn pthread_rwlock_tryrdlock +functions will return zero. +Otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_rwlock_tryrdlock +function will fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The lock could not be acquired because a writer holds the lock or +was blocked on it. +.El +.Pp +The +.Fn pthread_rwlock_rdlock +and +.Fn pthread_rwlock_tryrdlock +functions may fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The lock could not be acquired because the maximum number of read locks +against +.Fa lock +has been exceeded. +.It Bq Er EDEADLK +The current thread already owns +.Fa lock +for writing. +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.It Bq Er ENOMEM +Insufficient memory exists to initialize the lock (applies to +statically initialized locks only). +.El +.Sh SEE ALSO +.Xr pthread_rwlock_init 3 , +.Xr pthread_rwlock_trywrlock 3 , +.Xr pthread_rwlock_unlock 3 , +.Xr pthread_rwlock_wrlock 3 +.Sh STANDARDS +The +.Fn pthread_rwlock_rdlock +and +.Fn pthread_rwlock_tryrdlock +functions are expected to conform to +.St -susv2 . +.Sh HISTORY +The +.Fn pthread_rwlock_rdlock +function first appeared in +.Fx 3.0 . diff --git a/static/freebsd/man3/pthread_rwlock_timedrdlock.3 b/static/freebsd/man3/pthread_rwlock_timedrdlock.3 new file mode 100644 index 00000000..2b736529 --- /dev/null +++ b/static/freebsd/man3/pthread_rwlock_timedrdlock.3 @@ -0,0 +1,116 @@ +.\" Copyright (c) 2004 Michael Telahun Makonnen +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 17, 2018 +.Dt PTHREAD_RWLOCK_TIMEDRDLOCK 3 +.Os +.Sh NAME +.Nm pthread_rwlock_timedrdlock +.Nd "acquire a read-write lock for reading or give up after a specified period" +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_rwlock_timedrdlock "pthread_rwlock_t *restrict rwlock" "const struct timespec *restrict abs_timeout" +.Sh DESCRIPTION +This function acquires a read lock on the read-write lock +.Fa rwlock . +However, if the lock cannot be +acquired without waiting for another thread to +unlock the lock, +this wait shall be terminated when +.Fa abs_timeout +expires. +.Pp +A thread may hold multiple concurrent read locks. +The +.Xr pthread_rwlock_unlock 3 +function must be called once for each lock acquired. +.Pp +If the thread should be interrupted by a signal, +the +.Fn pthread_rwlock_timedrdlock +function will be automatically restarted after the thread returns from +the signal handler. +.Pp +The calling thread may deadlock if +at the time the call is made it holds a write lock on +.Fa rwlock . +The results are undefined if this function is called with +an uninitialized read-write lock. +.Sh IMPLEMENTATION NOTES +To prevent writer starvation, writers are favored over readers. +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlock_timedrdlock +function will return zero. +Otherwise, an error number will be returned to indicate the error. +.Pp +This function shall not return an error code of +.Er EINTR . +.Sh ERRORS +The +.Fn pthread_rwlock_timedrdlock +function will fail if: +.Bl -tag -width Er +.It Bq Er ETIMEDOUT +The lock could not be acquired before the specified timeout expired. +.El +.Pp +The +.Fn pthread_rwlock_timedrdlock +function may fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The read lock could not be +acquired because the maximum number of read locks for +.Fa rwlock +would be exceeded. +.It Bq Er EDEADLK +The calling thread already holds a write lock on +.Fa rwlock . +.It Bq Er EINVAL +The value specified by +.Fa rwlock +does not refer to an initialized read-write lock object, +or the +.Fa abs_timeout +nanosecond value is less than zero or +greater than or equal to 1 billion. +.El +.Sh SEE ALSO +.Xr pthread_rwlock_init 3 , +.Xr pthread_rwlock_timedwrlock 3 , +.Xr pthread_rwlock_unlock 3 +.Sh STANDARDS +The +.Fn pthread_rwlock_timedrdlock +function is expected to conform to +.St -p1003.1-96 . +.Sh HISTORY +The +.Fn pthread_rwlock_timedrdlock +function first appeared in +.Fx 5.2 . diff --git a/static/freebsd/man3/pthread_rwlock_timedwrlock.3 b/static/freebsd/man3/pthread_rwlock_timedwrlock.3 new file mode 100644 index 00000000..4543eff4 --- /dev/null +++ b/static/freebsd/man3/pthread_rwlock_timedwrlock.3 @@ -0,0 +1,106 @@ +.\" Copyright (c) 2004 Michael Telahun Makonnen +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 17, 2018 +.Dt PTHREAD_RWLOCK_TIMEDWRLOCK 3 +.Os +.Sh NAME +.Nm pthread_rwlock_timedwrlock +.Nd "acquire a read-write lock for writing or give up after a specified period" +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_rwlock_timedwrlock "pthread_rwlock_t *restrict rwlock" "const struct timespec *restrict abs_timeout" +.Sh DESCRIPTION +This function acquires a write lock on the read-write lock +.Fa rwlock . +However, if the lock cannot be +acquired without waiting for another thread to +unlock the lock, +this wait shall be terminated when +.Fa abs_timeout +expires. +.Pp +If the thread should be interrupted by a signal, +the +.Fn pthread_rwlock_timedwrlock +function will be automatically restarted after the thread returns from +the signal handler. +.Pp +The calling thread may deadlock if +at the time the call is made it holds +.Fa rwlock . +The results are undefined if this function is called with +an uninitialized read-write lock. +.Sh IMPLEMENTATION NOTES +To prevent writer starvation, writers are favored over readers. +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlock_timedwrlock +function will return zero. +Otherwise, an error number will be returned to indicate the error. +.Pp +This function shall not return an error code of +.Er EINTR . +.Sh ERRORS +The +.Fn pthread_rwlock_timedwrlock +function shall fail if: +.Bl -tag -width Er +.It Bq Er ETIMEDOUT +The lock could not be acquired before the specified timeout expired. +.El +.Pp +The +.Fn pthread_rwlock_timedwrlock +function may fail if: +.Bl -tag -width Er +.It Bq Er EDEADLK +The calling thread already holds +.Fa rwlock . +.It Bq Er EINVAL +The value specified by +.Fa rwlock +does not refer to an initialized read-write lock object, +or the +.Fa abs_timeout +nanosecond value is less than zero or +greater than or equal to 1 billion. +.El +.Sh SEE ALSO +.Xr pthread_rwlock_init 3 , +.Xr pthread_rwlock_timedrdlock 3 , +.Xr pthread_rwlock_unlock 3 +.Sh STANDARDS +The +.Fn pthread_rwlock_timedwrlock +function is expected to conform to +.St -p1003.1-96 . +.Sh HISTORY +The +.Fn pthread_rwlock_timedwrlock +function first appeared in +.Fx 5.2 . diff --git a/static/freebsd/man3/pthread_rwlock_unlock.3 b/static/freebsd/man3/pthread_rwlock_unlock.3 new file mode 100644 index 00000000..8e348e92 --- /dev/null +++ b/static/freebsd/man3/pthread_rwlock_unlock.3 @@ -0,0 +1,80 @@ +.\" Copyright (c) 1998 Alex Nash +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 4, 1998 +.Dt PTHREAD_RWLOCK_UNLOCK 3 +.Os +.Sh NAME +.Nm pthread_rwlock_unlock +.Nd release a read/write lock +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_rwlock_unlock "pthread_rwlock_t *lock" +.Sh DESCRIPTION +The +.Fn pthread_rwlock_unlock +function is used to release the read/write lock previously obtained by +.Fn pthread_rwlock_rdlock , +.Fn pthread_rwlock_wrlock , +.Fn pthread_rwlock_tryrdlock , +or +.Fn pthread_rwlock_trywrlock . +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlock_unlock +function will return zero. +Otherwise an error number will be returned +to indicate the error. +.Pp +The results are undefined if +.Fa lock +is not held by the calling thread. +.Sh ERRORS +The +.Fn pthread_rwlock_unlock +function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.It Bq Er EPERM +The current thread does not own the read/write lock. +.El +.Sh SEE ALSO +.Xr pthread_rwlock_rdlock 3 , +.Xr pthread_rwlock_wrlock 3 +.Sh STANDARDS +The +.Fn pthread_rwlock_unlock +function is expected to conform to +.St -susv2 . +.Sh HISTORY +The +.Fn pthread_rwlock_unlock +function first appeared in +.Fx 3.0 . diff --git a/static/freebsd/man3/pthread_rwlock_wrlock.3 b/static/freebsd/man3/pthread_rwlock_wrlock.3 new file mode 100644 index 00000000..58416b27 --- /dev/null +++ b/static/freebsd/man3/pthread_rwlock_wrlock.3 @@ -0,0 +1,104 @@ +.\" Copyright (c) 1998 Alex Nash +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 4, 1998 +.Dt PTHREAD_RWLOCK_WRLOCK 3 +.Os +.Sh NAME +.Nm pthread_rwlock_wrlock , +.Nm pthread_rwlock_trywrlock +.Nd acquire a read/write lock for writing +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_rwlock_wrlock "pthread_rwlock_t *lock" +.Ft int +.Fn pthread_rwlock_trywrlock "pthread_rwlock_t *lock" +.Sh DESCRIPTION +The +.Fn pthread_rwlock_wrlock +function blocks until a write lock can be acquired against +.Fa lock . +The +.Fn pthread_rwlock_trywrlock +function performs the same action, but does not block if the lock +cannot be immediately obtained. +.Pp +The results are undefined if the calling thread already holds the +lock at the time the call is made. +.Sh IMPLEMENTATION NOTES +To prevent writer starvation, writers are favored over readers. +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlock_wrlock +and +.Fn pthread_rwlock_trywrlock +functions will return zero. +Otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_rwlock_trywrlock +function will fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +The calling thread is not able to acquire the lock without blocking. +.El +.Pp +The +.Fn pthread_rwlock_wrlock +and +.Fn pthread_rwlock_trywrlock +functions may fail if: +.Bl -tag -width Er +.It Bq Er EDEADLK +The calling thread already owns the read/write lock (for reading +or writing). +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.It Bq Er ENOMEM +Insufficient memory exists to initialize the lock (applies to +statically initialized locks only). +.El +.Sh SEE ALSO +.Xr pthread_rwlock_init 3 , +.Xr pthread_rwlock_rdlock 3 , +.Xr pthread_rwlock_tryrdlock 3 , +.Xr pthread_rwlock_unlock 3 +.Sh STANDARDS +The +.Fn pthread_rwlock_wrlock +and +.Fn pthread_rwlock_trywrlock +functions are expected to conform to +.St -susv2 . +.Sh HISTORY +The +.Fn pthread_rwlock_wrlock +function first appeared in +.Fx 3.0 . diff --git a/static/freebsd/man3/pthread_rwlockattr_destroy.3 b/static/freebsd/man3/pthread_rwlockattr_destroy.3 new file mode 100644 index 00000000..eabfbad7 --- /dev/null +++ b/static/freebsd/man3/pthread_rwlockattr_destroy.3 @@ -0,0 +1,70 @@ +.\" Copyright (c) 1998 Alex Nash +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 4, 1998 +.Dt PTHREAD_RWLOCKATTR_DESTROY 3 +.Os +.Sh NAME +.Nm pthread_rwlockattr_destroy +.Nd destroy a read/write lock attributes object +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_rwlockattr_destroy "pthread_rwlockattr_t *attr" +.Sh DESCRIPTION +The +.Fn pthread_rwlockattr_destroy +function is used to destroy a read/write lock attributes object +previously created with +.Fn pthread_rwlockattr_init . +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlockattr_destroy +function will return zero. +Otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_rwlockattr_destroy +function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_rwlockattr_init 3 +.Sh STANDARDS +The +.Fn pthread_rwlockattr_destroy +function is expected to conform to +.St -susv2 . +.Sh HISTORY +The +.Fn pthread_rwlockattr_destroy +function first appeared in +.Fx 3.0 . diff --git a/static/freebsd/man3/pthread_rwlockattr_getpshared.3 b/static/freebsd/man3/pthread_rwlockattr_getpshared.3 new file mode 100644 index 00000000..33d7cd32 --- /dev/null +++ b/static/freebsd/man3/pthread_rwlockattr_getpshared.3 @@ -0,0 +1,86 @@ +.\" Copyright (c) 1998 Alex Nash +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 17, 2018 +.Dt PTHREAD_RWLOCKATTR_GETPSHARED 3 +.Os +.Sh NAME +.Nm pthread_rwlockattr_getpshared +.Nd get the process shared attribute +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fo pthread_rwlockattr_getpshared +.Fa "const pthread_rwlockattr_t *restrict attr" "int *restrict pshared" +.Fc +.Sh DESCRIPTION +The +.Fn pthread_rwlockattr_getpshared +function is used to get the process shared setting of a read/write +lock attribute object. +The setting is returned via +.Fa pshared , +and may be one of two values: +.Bl -tag -width PTHREAD_PROCESS_PRIVATE +.It Dv PTHREAD_PROCESS_SHARED +Any thread of any process that has access to the memory where the +read/write lock resides can manipulate the lock. +.It Dv PTHREAD_PROCESS_PRIVATE +Only threads created within the same process as the thread that +initialized the read/write lock can manipulate the lock. +This is +the default value. +.El +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlockattr_getpshared +function will return zero. +Otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_rwlockattr_getpshared +function may fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_rwlock_init 3 , +.Xr pthread_rwlockattr_init 3 , +.Xr pthread_rwlockattr_setpshared 3 +.Sh STANDARDS +The +.Fn pthread_rwlockattr_getpshared +function is expected to conform to +.St -susv2 . +.Sh HISTORY +The +.Fn pthread_rwlockattr_getpshared +function first appeared in +.Fx 3.0 . diff --git a/static/freebsd/man3/pthread_rwlockattr_init.3 b/static/freebsd/man3/pthread_rwlockattr_init.3 new file mode 100644 index 00000000..031d010a --- /dev/null +++ b/static/freebsd/man3/pthread_rwlockattr_init.3 @@ -0,0 +1,69 @@ +.\" Copyright (c) 1998 Alex Nash +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 4, 1998 +.Dt PTHREAD_RWLOCKATTR_INIT 3 +.Os +.Sh NAME +.Nm pthread_rwlockattr_init +.Nd initialize a read/write lock attributes object +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_rwlockattr_init "pthread_rwlockattr_t *attr" +.Sh DESCRIPTION +The +.Fn pthread_rwlockattr_init +function is used to initialize a read/write lock attributes object. +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlockattr_init +function will return zero. +Otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_rwlockattr_init +function will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient memory exists to initialize the attributes object. +.El +.Sh SEE ALSO +.Xr pthread_rwlock_init 3 , +.Xr pthread_rwlockattr_destroy 3 , +.Xr pthread_rwlockattr_getpshared 3 , +.Xr pthread_rwlockattr_setpshared 3 +.Sh STANDARDS +The +.Fn pthread_rwlockattr_init +function is expected to conform to +.St -susv2 . +.Sh HISTORY +The +.Fn pthread_rwlockattr_init +function first appeared in +.Fx 3.0 . diff --git a/static/freebsd/man3/pthread_rwlockattr_setpshared.3 b/static/freebsd/man3/pthread_rwlockattr_setpshared.3 new file mode 100644 index 00000000..3ed86f41 --- /dev/null +++ b/static/freebsd/man3/pthread_rwlockattr_setpshared.3 @@ -0,0 +1,90 @@ +.\" Copyright (c) 1998 Alex Nash +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd May 31, 2016 +.Dt PTHREAD_RWLOCKATTR_SETPSHARED 3 +.Os +.Sh NAME +.Nm pthread_rwlockattr_setpshared +.Nd set the process shared attribute +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_rwlockattr_setpshared "pthread_rwlockattr_t *attr" "int pshared" +.Sh DESCRIPTION +The +.Fn pthread_rwlockattr_setpshared +function sets the process shared attribute of +.Fa attr +to the value referenced by +.Fa pshared . +The +.Fa pshared +argument may be one of two values: +.Bl -tag -width PTHREAD_PROCESS_PRIVATE +.It Dv PTHREAD_PROCESS_SHARED +Any thread of any process that has access to the memory where the +read/write lock resides can manipulate the lock. +.It Dv PTHREAD_PROCESS_PRIVATE +Only threads created within the same process as the thread that +initialized the read/write lock can manipulate the lock. +This is +the default value. +.El +.Sh RETURN VALUES +If successful, the +.Fn pthread_rwlockattr_setpshared +function will return zero. +Otherwise an error number will be returned +to indicate the error. +.Sh ERRORS +The +.Fn pthread_rwlockattr_setpshared +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa attr +or +.Fa pshared +is invalid. +.El +.Sh SEE ALSO +.Xr pthread_rwlock_init 3 , +.Xr pthread_rwlockattr_getpshared 3 , +.Xr pthread_rwlockattr_init 3 +.Sh STANDARDS +The +.Fn pthread_rwlockattr_setpshared +function is expected to conform to +.St -susv2 . +.Sh HISTORY +The +.Fn pthread_rwlockattr_setpshared +function first appeared in +.Fx 3.0 . +Support for process-shared read/write locks appeared in +.Fx 11.0 . diff --git a/static/freebsd/man3/pthread_schedparam.3 b/static/freebsd/man3/pthread_schedparam.3 new file mode 100644 index 00000000..3ba17578 --- /dev/null +++ b/static/freebsd/man3/pthread_schedparam.3 @@ -0,0 +1,100 @@ +.\" Copyright (C) 2000 Jason Evans <jasone@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(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 October 17, 2022 +.Dt PTHREAD_SCHEDPARAM 3 +.Os +.Sh NAME +.Nm pthread_setschedparam , +.Nm pthread_getschedparam +.Nd thread scheduling parameter manipulation +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_setschedparam "pthread_t thread" "int policy" "const struct sched_param *param" +.Ft int +.Fn pthread_getschedparam "pthread_t thread" "int *restrict policy" "struct sched_param *restrict param" +.Sh DESCRIPTION +The +.Fn pthread_setschedparam +and +.Fn pthread_getschedparam +functions set and get the scheduling parameters of individual threads. +The scheduling policy for a thread can either be +.Dv SCHED_FIFO +(first in, first out), +.Dv SCHED_RR +(round-robin), or +.Dv SCHED_OTHER +(timesharing). +Valid thread priorities (accessed via +.Va param->sched_priority ) +must be within the range returned by the +.Xr sched_get_priority_min 2 +and +.Xr sched_get_priority_max 2 +system calls. +.Sh RETURN VALUES +If successful, these functions return 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_setschedparam +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +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 . +.El +.Pp +The +.Fn pthread_getschedparam +function will fail if: +.Bl -tag -width Er +.It Bq Er ESRCH +Non-existent thread +.Fa thread . +.El +.Sh SEE ALSO +.Xr sched_get_priority_max 2 , +.Xr sched_get_priority_min 2 +.Sh STANDARDS +The +.Fn pthread_setschedparam +and +.Fn pthread_getschedparam +functions conform to +.St -susv2 . diff --git a/static/freebsd/man3/pthread_self.3 b/static/freebsd/man3/pthread_self.3 new file mode 100644 index 00000000..1c485300 --- /dev/null +++ b/static/freebsd/man3/pthread_self.3 @@ -0,0 +1,61 @@ +.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 4, 1996 +.Dt PTHREAD_SELF 3 +.Os +.Sh NAME +.Nm pthread_self +.Nd get the calling thread's ID +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft pthread_t +.Fn pthread_self "void" +.Sh DESCRIPTION +The +.Fn pthread_self +function returns the thread ID of the calling thread. +.Sh RETURN VALUES +The +.Fn pthread_self +function returns the thread ID of the calling thread. +.Sh ERRORS +None. +.Sh SEE ALSO +.Xr pthread_create 3 , +.Xr pthread_equal 3 , +.Xr pthread_getthreadid_np 3 +.Sh STANDARDS +The +.Fn pthread_self +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_set_name_np.3 b/static/freebsd/man3/pthread_set_name_np.3 new file mode 100644 index 00000000..69adcad2 --- /dev/null +++ b/static/freebsd/man3/pthread_set_name_np.3 @@ -0,0 +1,107 @@ +.\" 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. +.\" +.Dd October 12, 2021 +.Dt PTHREAD_SET_NAME_NP 3 +.Os +.Sh NAME +.Nm pthread_get_name_np , +.Nm pthread_getname_np , +.Nm pthread_set_name_np , +.Nm pthread_setname_np +.Nd set and retrieve the thread name +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft void +.Fn pthread_get_name_np "pthread_t thread" "char *name" "size_t len" +.Ft int +.Fn pthread_getname_np "pthread_t thread" "char *name" "size_t len" +.Ft void +.Fn pthread_set_name_np "pthread_t thread" "const char *name" +.Ft int +.Fn pthread_setname_np "pthread_t thread" "const char *name" +.Sh DESCRIPTION +The +.Fn pthread_set_name_np +and +.Fn pthread_setname_np +functions apply a copy of the given +.Fa name +to the given +.Fa thread . +.Pp +The +.Fn pthread_get_name_np +and +.Fn pthread_getname_np +functions retrieve the +.Fa name +associated with +.Fa thread . +If +.Fn pthread_set_name_np +was not previously called for +.Fa thread , +the buffer pointed to by +.Fa name +will be empty. +.Sh ERRORS +The +.Nm pthread_getname_np +and +.Nm pthread_setname_np +will fail if +.Bl -tag -width Er +.It Bq Er ESRCH +No thread could be found in the current process corresponding to that +specified by the given thread ID +.Fa thread . +.El +.Pp +Because of the debugging nature of +.Nm pthread_get_name_np +and +.Nm pthread_set_name_np +functions, all errors that may +appear inside are silently ignored. +.Sh SEE ALSO +.Xr thr_set_name 2 , +.Xr pthread_np 3 +.Sh STANDARDS +.Fn pthread_set_name_np +and +.Fn pthread_get_name_np +are non-standard extensions. +.Fn pthread_setname_np +and +.Fn pthread_getname_np +are also non-standard, but are implemented by larger number of operating +systems so they are in fact more portable. +.Sh AUTHORS +This manual page was written by +.An Alexey Zelkin Aq Mt phantom@FreeBSD.org +and +.An Yuri Pankov Aq Mt yuripv@yuripv.net . diff --git a/static/freebsd/man3/pthread_setspecific.3 b/static/freebsd/man3/pthread_setspecific.3 new file mode 100644 index 00000000..59079e35 --- /dev/null +++ b/static/freebsd/man3/pthread_setspecific.3 @@ -0,0 +1,99 @@ +.\" Copyright (c) 1996 John Birrell <jb@cimlogic.com.au>. +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by John Birrell. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 4, 1996 +.Dt PTHREAD_SETSPECIFIC 3 +.Os +.Sh NAME +.Nm pthread_setspecific +.Nd set a thread-specific data value +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_setspecific "pthread_key_t key" "const void *value" +.Sh DESCRIPTION +The +.Fn pthread_setspecific +function associates a thread-specific value with a +.Fa key +obtained via a previous call to +.Fn pthread_key_create . +Different threads can bind different values to the same key. +These values are +typically pointers to blocks of dynamically allocated memory that have been +reserved for use by the calling thread. +.Pp +The effect of calling +.Fn pthread_setspecific +with a key value not obtained from +.Fn pthread_key_create +or after +.Fa key +has been deleted with +.Fn pthread_key_delete +is undefined. +.Pp +The +.Fn pthread_setspecific +function may be called from a thread-specific data destructor function, +however this may result in lost storage or infinite loops if doing so +causes non-NULL key values to remain after +.Bq PTHREAD_DESTRUCTOR_ITERATIONS +iterations of destructor calls have been made. +.Sh RETURN VALUES +If successful, the +.Fn pthread_setspecific +function will return zero. +Otherwise an error number will be returned to +indicate the error. +.Sh ERRORS +The +.Fn pthread_setspecific +function will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Insufficient memory exists to associate the value with the +.Fa key . +.It Bq Er EINVAL +The +.Fa key +value is invalid. +.El +.Sh SEE ALSO +.Xr pthread_getspecific 3 , +.Xr pthread_key_create 3 , +.Xr pthread_key_delete 3 +.Sh STANDARDS +The +.Fn pthread_setspecific +function conforms to +.St -p1003.1-96 . diff --git a/static/freebsd/man3/pthread_sigmask.3 b/static/freebsd/man3/pthread_sigmask.3 new file mode 100644 index 00000000..8d2a5d65 --- /dev/null +++ b/static/freebsd/man3/pthread_sigmask.3 @@ -0,0 +1,97 @@ +.\" Copyright (C) 2000 Jason Evans <jasone@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(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 February 19, 2011 +.Dt PTHREAD_SIGMASK 3 +.Os +.Sh NAME +.Nm pthread_sigmask +.Nd examine and/or change a thread's signal mask +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.In signal.h +.Ft int +.Fn pthread_sigmask "int how" "const sigset_t * restrict set" \ + "sigset_t * restrict oset" +.Sh DESCRIPTION +The +.Fn pthread_sigmask +function examines and/or changes the calling thread's signal mask. +.Pp +If +.Fa set +is not +.Dv NULL , +it specifies a set of signals to be modified, and +.Fa how +specifies what to set the signal mask to: +.Bl -tag -width SIG_UNBLOCK +.It Dv SIG_BLOCK +Union of the current mask and +.Fa set . +.It Dv SIG_UNBLOCK +Intersection of the current mask and the complement of +.Fa set . +.It Dv SIG_SETMASK +.Fa set . +.El +.Pp +If +.Fa oset +is not NULL, the previous signal mask is stored in the location pointed to by +.Fa oset . +.Pp +.Dv SIGKILL +and +.Dv SIGSTOP +cannot be blocked, and will be silently ignored if included in the signal mask. +.Sh RETURN VALUES +If successful, +.Fn pthread_sigmask +returns 0. +Otherwise, an error is returned. +.Sh ERRORS +The +.Fn pthread_sigmask +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +.Fa how +is not one of the defined values. +.El +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr sigpending 2 , +.Xr sigprocmask 2 , +.Xr sigsuspend 2 , +.Xr sigsetops 3 +.Sh STANDARDS +The +.Fn pthread_sigmask +function conforms to +.St -p1003.1-96 diff --git a/static/freebsd/man3/pthread_signals_block_np.3 b/static/freebsd/man3/pthread_signals_block_np.3 new file mode 100644 index 00000000..de33f4e6 --- /dev/null +++ b/static/freebsd/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/static/freebsd/man3/pthread_sigqueue.3 b/static/freebsd/man3/pthread_sigqueue.3 new file mode 100644 index 00000000..852f6314 --- /dev/null +++ b/static/freebsd/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/static/freebsd/man3/pthread_spin_init.3 b/static/freebsd/man3/pthread_spin_init.3 new file mode 100644 index 00000000..4820ddcf --- /dev/null +++ b/static/freebsd/man3/pthread_spin_init.3 @@ -0,0 +1,123 @@ +.\" Copyright (c) 2004 Michael Telahun Makonnen +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd May 31, 2016 +.Dt PTHREAD_SPIN_INIT 3 +.Os +.Sh NAME +.Nm pthread_spin_init , pthread_spin_destroy +.Nd "initialize or destroy a spin lock" +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_spin_init "pthread_spinlock_t *lock" "int pshared" +.Ft int +.Fn pthread_spin_destroy "pthread_spinlock_t *lock" +.Sh DESCRIPTION +The +.Fn pthread_spin_init +function will initialize +.Fa lock +to an unlocked state and +allocate any resources necessary to begin using it. +If +.Fa pshared +is set to +.Dv PTHREAD_PROCESS_SHARED , +any thread, +whether belonging to the process in which the spinlock was created or not, +that has access to the memory area where +.Fa lock +resides, can use +.Fa lock . +If it is set to +.Dv PTHREAD_PROCESS_PRIVATE , +it can only be used by threads within the same process. +.Pp +The +.Fn pthread_spin_destroy +function will destroy +.Fa lock +and release any resources that may have been allocated on its behalf. +.Sh RETURN VALUES +If successful, +both +.Fn pthread_spin_init +and +.Fn pthread_spin_destroy +will return zero. +Otherwise, an error number will be returned to indicate the error. +.Pp +Neither of these functions will return +.Er EINTR . +.Sh ERRORS +The +.Fn pthread_spin_init +and +.Fn pthread_spin_destroy +functions will fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +An attempt to initialize or destroy +.Fa lock +while it is in use. +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid. +.El +.Pp +The +.Fn pthread_spin_init +function will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +Insufficient resources, +other than memory, +to initialize +.Fa lock . +.It Bq Er ENOMEM +Insufficient memory to initialize +.Fa lock . +.El +.Sh SEE ALSO +.Xr pthread_spin_lock 3 , +.Xr pthread_spin_unlock 3 +.Sh HISTORY +The +.Fn pthread_spin_init +and +.Fn pthread_spin_destroy +functions first appeared in +.Lb libkse +in +.Fx 5.2 , +and in +.Lb libthr +in +.Fx 5.3 . +Support for process-shared spinlocks appeared in +.Fx 11.0 . diff --git a/static/freebsd/man3/pthread_spin_lock.3 b/static/freebsd/man3/pthread_spin_lock.3 new file mode 100644 index 00000000..4308271a --- /dev/null +++ b/static/freebsd/man3/pthread_spin_lock.3 @@ -0,0 +1,136 @@ +.\" Copyright (c) 2004 Michael Telahun Makonnen +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd January 22, 2004 +.Dt PTHREAD_SPIN_LOCK 3 +.Os +.Sh NAME +.Nm pthread_spin_lock , pthread_spin_trylock , pthread_spin_unlock +.Nd "lock or unlock a spin lock" +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_spin_lock "pthread_spinlock_t *lock" +.Ft int +.Fn pthread_spin_trylock "pthread_spinlock_t *lock" +.Ft int +.Fn pthread_spin_unlock "pthread_spinlock_t *lock" +.Sh DESCRIPTION +The +.Fn pthread_spin_lock +function will acquire +.Fa lock +if it is not currently owned by another thread. +If the lock cannot be acquired immediately, it will +spin attempting to acquire the lock (it will not sleep) until +it becomes available. +.Pp +The +.Fn pthread_spin_trylock +function is the same as +.Fn pthread_spin_lock +except that if it cannot acquire +.Fa lock +immediately it will return with an error. +.Pp +The +.Fn pthread_spin_unlock +function will release +.Fa lock , +which must have been previously locked by a call to +.Fn pthread_spin_lock +or +.Fn pthread_spin_trylock . +.Sh RETURN VALUES +If successful, all these functions will return zero. +Otherwise, an error number will be returned to indicate the error. +.Pp +None of these functions will return +.Er EINTR . +.Sh ERRORS +The +.Fn pthread_spin_lock , +.Fn pthread_spin_trylock +and +.Fn pthread_spin_unlock +functions will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The value specified by +.Fa lock +is invalid or is not initialized. +.El +.Pp +The +.Fn pthread_spin_lock +function may fail if: +.Bl -tag -width Er +.It Bq Er EDEADLK +The calling thread already owns the lock. +.El +.Pp +The +.Fn pthread_spin_trylock +function will fail if: +.Bl -tag -width Er +.It Bq Er EBUSY +Another thread currently holds +.Fa lock . +.El +.Pp +The +.Fn pthread_spin_unlock +function may fail if: +.Bl -tag -width Er +.It Bq Er EPERM +The calling thread does not own +.Fa lock . +.El +.Sh SEE ALSO +.Xr pthread_spin_destroy 3 , +.Xr pthread_spin_init 3 +.Sh HISTORY +The +.Fn pthread_spin_lock , +.Fn pthread_spin_trylock +and +.Fn pthread_spin_unlock +functions first appeared in +.Lb libkse +in +.Fx 5.2 , +and in +.Lb libthr +in +.Fx 5.3 . +.Sh BUGS +The implementation of +.Fn pthread_spin_lock , +.Fn pthread_spin_trylock +and +.Fn pthread_spin_unlock +is expected to conform to +.St -p1003.2 . diff --git a/static/freebsd/man3/pthread_suspend_all_np.3 b/static/freebsd/man3/pthread_suspend_all_np.3 new file mode 100644 index 00000000..c99a08a0 --- /dev/null +++ b/static/freebsd/man3/pthread_suspend_all_np.3 @@ -0,0 +1,59 @@ +.\" 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. +.\" +.Dd October 12, 2021 +.Dt PTHREAD_SUSPEND_ALL_NP 3 +.Os +.Sh NAME +.Nm pthread_suspend_all_np +.Nd suspend all active threads +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft void +.Fn pthread_suspend_all_np void +.Sh DESCRIPTION +The +.Fn pthread_suspend_all_np +function causes all active threads to be suspended. +The only exception is the current thread, +the thread that called the +.Fn pthread_suspend_all_np +function. +.Pp +It is not safe for the caller of the +.Fn pthread_suspend_all_np +function to use any non-async signal safe functions, besides +.Xr pthread_resume_all_np 3 , +until threads are resumed, unless measures are taken to ensure +that all threads are suspended at safe points. +.Sh SEE ALSO +.Xr pthread_np 3 , +.Xr pthread_resume_all_np 3 , +.Xr pthread_resume_np 3 , +.Xr pthread_suspend_np 3 +.Sh AUTHORS +This manual page was written by +.An Alexey Zelkin Aq Mt phantom@FreeBSD.org . diff --git a/static/freebsd/man3/pthread_suspend_np.3 b/static/freebsd/man3/pthread_suspend_np.3 new file mode 100644 index 00000000..8e05bac0 --- /dev/null +++ b/static/freebsd/man3/pthread_suspend_np.3 @@ -0,0 +1,76 @@ +.\" 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. +.\" +.Dd October 12, 2021 +.Dt PTHREAD_SUSPEND_NP 3 +.Os +.Sh NAME +.Nm pthread_suspend_np +.Nd suspend a thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft int +.Fn pthread_suspend_np "pthread_t tid" +.Sh DESCRIPTION +The +.Fn pthread_suspend_np +function, called on an active thread, causes it to suspend. +.Pp +It is not safe for the caller of the +.Fn pthread_suspend_np +function to use any non-async signal safe functions, except +.Xr pthread_resume_np 3 , +until suspended thread is resumed, unless measures are taken to ensure +that the thread is suspended at a safe point. +.Sh RETURN VALUES +If successful, +.Fn pthread_suspend_np +function returns 0. +Otherwise, an error number is returned to indicate the error. +.Sh ERRORS +The +.Fn pthread_suspend_np +function will fail if: +.Bl -tag -width Er +.It Bq Er EDEADLK +An attempt was made to suspend the current thread. +.It Bq Er EINVAL +The value specified by the +.Fa tid +argument is invalid. +.It Bq Er ESRCH +No thread could be found corresponding to the thread ID specified by the +.Fa tid +argument. +.El +.Sh SEE ALSO +.Xr pthread_np 3 , +.Xr pthread_resume_all_np 3 , +.Xr pthread_resume_np 3 , +.Xr pthread_suspend_all_np 3 +.Sh AUTHORS +This manual page was written by +.An Alexey Zelkin Aq Mt phantom@FreeBSD.org . diff --git a/static/freebsd/man3/pthread_testcancel.3 b/static/freebsd/man3/pthread_testcancel.3 new file mode 100644 index 00000000..c74cdcfe --- /dev/null +++ b/static/freebsd/man3/pthread_testcancel.3 @@ -0,0 +1,263 @@ +.Dd March 18, 2017 +.Dt PTHREAD_TESTCANCEL 3 +.Os +.Sh NAME +.Nm pthread_setcancelstate , +.Nm pthread_setcanceltype , +.Nm pthread_testcancel +.Nd set cancelability state +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft int +.Fn pthread_setcancelstate "int state" "int *oldstate" +.Ft int +.Fn pthread_setcanceltype "int type" "int *oldtype" +.Ft void +.Fn pthread_testcancel "void" +.Sh DESCRIPTION +The +.Fn pthread_setcancelstate +function atomically both sets the calling thread's cancelability state +to the indicated +.Fa state +and, if +.Fa oldstate +is not +.Dv NULL , +returns the previous cancelability state at the location referenced by +.Fa oldstate . +Legal values for +.Fa state +are +.Dv PTHREAD_CANCEL_ENABLE +and +.Dv PTHREAD_CANCEL_DISABLE . +The function is async-signal-safe. +.Pp +The +.Fn pthread_setcanceltype +function atomically both sets the calling thread's cancelability type +to the indicated +.Fa type +and, if +.Fa oldtype +is not +.Dv NULL , +returns the previous cancelability type at the location referenced by +.Fa oldtype . +Legal values for +.Fa type +are +.Dv PTHREAD_CANCEL_DEFERRED +and +.Dv PTHREAD_CANCEL_ASYNCHRONOUS . +.Pp +The cancelability state and type of any newly created threads, including the +thread in which +.Fn main +was first invoked, are +.Dv PTHREAD_CANCEL_ENABLE +and +.Dv PTHREAD_CANCEL_DEFERRED +respectively. +.Pp +The +.Fn pthread_testcancel +function creates a cancellation point in the calling thread. +The +.Fn pthread_testcancel +function has no effect if cancelability is disabled. +.Ss Cancelability States +The cancelability state of a thread determines the action taken upon +receipt of a cancellation request. +The thread may control cancellation in +a number of ways. +.Pp +Each thread maintains its own +.Dq cancelability state +which may be encoded in two bits: +.Bl -hang +.It Em Cancelability Enable +When cancelability is +.Dv PTHREAD_CANCEL_DISABLE , +cancellation requests against the target thread are held pending. +.It Em Cancelability Type +When cancelability is enabled and the cancelability type is +.Dv PTHREAD_CANCEL_ASYNCHRONOUS , +new or pending cancellation requests may be acted upon at any time. +When cancelability is enabled and the cancelability type is +.Dv PTHREAD_CANCEL_DEFERRED , +cancellation requests are held pending until a cancellation point (see +below) is reached. +If cancelability is disabled, the setting of the +cancelability type has no immediate effect as all cancellation requests +are held pending; however, once cancelability is enabled again the new +type will be in effect. +.El +.Ss Cancellation Points +Cancellation points will occur when a thread is executing the following +functions: +.Bl -tag -width "Fn pthread_cond_timedwait" -compact +.It Fn accept +.It Fn accept4 +.It Fn aio_suspend +.It Fn connect +.It Fn clock_nanosleep +.It Fn close +.It Fn creat +.It Fn fcntl +The +.Fn fcntl +function is a cancellation point if +.Fa cmd +is +.Dv F_SETLKW . +.It Fn fdatasync +.It Fn fsync +.It Fn kevent +The +.Fn kevent +function is a cancellation point if it is potentially blocking, +such as when the +.Fa nevents +argument is non-zero. +.It Fn mq_receive +.It Fn mq_send +.It Fn mq_timedreceive +.It Fn mq_timedsend +.It Fn msync +.It Fn nanosleep +.It Fn open +.It Fn openat +.It Fn pause +.It Fn poll +.It Fn ppoll +.It Fn pselect +.It Fn pthread_cond_timedwait +.It Fn pthread_cond_wait +.It Fn pthread_join +.It Fn pthread_testcancel +.It Fn read +.It Fn readv +.It Fn recv +.It Fn recvfrom +.It Fn recvmsg +.It Fn select +.It Fn sem_timedwait +.It Fn sem_clockwait_np +.It Fn sem_wait +.It Fn send +.It Fn sendmsg +.It Fn sendto +.It Fn sigsuspend +.It Fn sigtimedwait +.It Fn sigwaitinfo +.It Fn sigwait +.It Fn sleep +.It Fn system +.It Fn tcdrain +.It Fn usleep +.It Fn wait +.It Fn wait3 +.It Fn wait4 +.It Fn wait6 +.It Fn waitid +.It Fn waitpid +.It Fn write +.It Fn writev +.El +.Sh NOTES +The +.Fn pthread_setcancelstate +and +.Fn pthread_setcanceltype +functions are used to control the points at which a thread may be +asynchronously canceled. +For cancellation control to be usable in modular +fashion, some rules must be followed. +.Pp +For purposes of this discussion, consider an object to be a generalization +of a procedure. +It is a set of procedures and global variables written as +a unit and called by clients not known by the object. +Objects may depend +on other objects. +.Pp +First, cancelability should only be disabled on entry to an object, never +explicitly enabled. +On exit from an object, the cancelability state should +always be restored to its value on entry to the object. +.Pp +This follows from a modularity argument: if the client of an object (or the +client of an object that uses that object) has disabled cancelability, it is +because the client does not want to have to worry about how to clean up if the +thread is canceled while executing some sequence of actions. +If an object +is called in such a state and it enables cancelability and a cancellation +request is pending for that thread, then the thread will be canceled, +contrary to the wish of the client that disabled. +.Pp +Second, the cancelability type may be explicitly set to either +.Em deferred +or +.Em asynchronous +upon entry to an object. +But as with the cancelability state, on exit from +an object that cancelability type should always be restored to its value on +entry to the object. +.Pp +Finally, only functions that are cancel-safe may be called from a thread that +is asynchronously cancelable. +.Sh RETURN VALUES +If successful, the +.Fn pthread_setcancelstate +and +.Fn pthread_setcanceltype +functions will return zero. +Otherwise, an error number shall be returned to +indicate the error. +.Sh ERRORS +The function +.Fn pthread_setcancelstate +may fail with: +.Bl -tag -width Er +.It Bq Er EINVAL +The specified state is not +.Dv PTHREAD_CANCEL_ENABLE +or +.Dv PTHREAD_CANCEL_DISABLE . +.El +.Pp +The function +.Fn pthread_setcanceltype +may fail with: +.Bl -tag -width Er +.It Bq Er EINVAL +The specified state is not +.Dv PTHREAD_CANCEL_DEFERRED +or +.Dv PTHREAD_CANCEL_ASYNCHRONOUS . +.El +.Sh SEE ALSO +.Xr pthread_cancel 3 +.Sh STANDARDS +The +.Fn pthread_testcancel +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 +for the +.Ox +implementation of +.Xr pthread_cancel 3 . diff --git a/static/freebsd/man3/pthread_yield.3 b/static/freebsd/man3/pthread_yield.3 new file mode 100644 index 00000000..e9ef6491 --- /dev/null +++ b/static/freebsd/man3/pthread_yield.3 @@ -0,0 +1,28 @@ +.\" $OpenBSD: pthread_yield.3,v 1.3 2004/01/25 14:48:32 jmc Exp $ +.\" +.\" PUBLIC DOMAIN: No Rights Reserved. Marco S Hyman <marc@snafu.org> +.\" +.Dd September 18, 2006 +.Dt PTHREAD_YIELD 3 +.Os +.Sh NAME +.Nm pthread_yield +.Nd yield control of the current thread +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread.h +.Ft void +.Fn pthread_yield void +.Sh DESCRIPTION +The +.Fn pthread_yield +forces the running thread to relinquish the processor until it again +becomes the head of its thread list. +.Sh SEE ALSO +.Xr sched_yield 2 +.Sh STANDARDS +The +.Fn pthread_yield +is a non-portable (but quite common) extension to +.St -p1003.1-2001 . diff --git a/static/freebsd/man3/qmath.3 b/static/freebsd/man3/qmath.3 new file mode 100644 index 00000000..5c2332f0 --- /dev/null +++ b/static/freebsd/man3/qmath.3 @@ -0,0 +1,387 @@ +.\" +.\" Copyright (c) 2018 Netflix, Inc. +.\" 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, +.\" without modification, immediately at the beginning of the file. +.\" 2. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR +.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd July 4, 2019 +.Dt QMATH 3 +.Os +.Sh NAME +.Nm qmath +.Nd fixed-point math library based on the +.Dq Q +number format +.Sh SYNOPSIS +.In sys/qmath.h +.Sh DESCRIPTION +The +.Nm +data types and APIs support fixed-point math based on the +.Dq Q +number format. +The APIs have been built around the following data types: +.Vt s8q_t , +.Vt u8q_t , +.Vt s16q_t , +.Vt u16q_t , +.Vt s32q_t , +.Vt u32q_t , +.Vt s64q_t , +and +.Vt u64q_t , +which are referred to generically in the earlier API definitions as +.Fa QTYPE . +The +.Fa ITYPE +refers to the +.Xr stdint 7 +integer types. +.Fa NTYPE +is used to refer to any numeric type and is therefore a superset of +.Fa QTYPE +and +.Fa ITYPE . +.Pp +This scheme can represent Q numbers with +.Bq 2, 4, 6, 8, 16, 32, 48 +bits of precision after the binary radix point, +depending on the +.Fa rpshft +argument to +.Fn Q_INI . +The number of bits available for the integral component is not explicitly +specified, and implicitly consumes the remaining available bits of the chosen Q +data type. +.Pp +Operations on Q numbers maintain the precision of their arguments. +The fractional component is truncated to fit into the destination, +with no rounding. +None of the operations is affected by the floating-point environment. +.Pp +For more details, see the +.Sx IMPLEMENTATION DETAILS +below. +.Sh LIST OF FUNCTIONS +.de Cl +.Bl -column "isgreaterequal" "bessel function of the second kind of the order 0" +.Em "Name Description" +.. +.Ss Functions which create/initialise a Q number +.Cl +.Xr Q_INI 3 initialise a Q number +.El +.Ss Numeric functions which operate on two Q numbers +.Cl +.Xr Q_QADDQ 3 addition +.Xr Q_QDIVQ 3 division +.Xr Q_QMULQ 3 multiplication +.Xr Q_QSUBQ 3 subtraction +.Xr Q_NORMPREC 3 normalisation +.Xr Q_QMAXQ 3 maximum function +.Xr Q_QMINQ 3 minimum function +.Xr Q_QCLONEQ 3 identical copy +.Xr Q_QCPYVALQ 3 representational copy +.El +.Ss Numeric functions which apply integers to a Q number +.Cl +.Xr Q_QADDI 3 addition +.Xr Q_QDIVI 3 division +.Xr Q_QMULI 3 multiplication +.Xr Q_QSUBI 3 subtraction +.Xr Q_QFRACI 3 fraction +.Xr Q_QCPYVALI 3 overwrite +.El +.Ss Numeric functions which operate on a single Q number +.Cl +.Xr Q_QABS 3 absolute value +.Xr Q_Q2D 3 double representation +.Xr Q_Q2F 3 float representation +.El +.Ss Comparison and logic functions +.Cl +.Xr Q_SIGNED 3 determine sign +.Xr Q_LTZ 3 less than zero +.Xr Q_PRECEQ 3 compare bits +.Xr Q_QLTQ 3 less than +.Xr Q_QLEQ 3 less or equal +.Xr Q_QGTQ 3 greater than +.Xr Q_QGEQ 3 greater or equal +.Xr Q_QEQ 3 equal +.Xr Q_QNEQ 3 not equal +.Xr Q_OFLOW 3 would overflow +.Xr Q_RELPREC 3 relative precision +.El +.Ss Functions which manipulate the control/sign data bits +.Cl +.Xr Q_SIGNSHFT 3 sign bit position +.Xr Q_SSIGN 3 sign bit +.Xr Q_CRAWMASK 3 control bitmask +.Xr Q_SRAWMASK 3 sign bitmask +.Xr Q_GCRAW 3 raw control bits +.Xr Q_GCVAL 3 value of control bits +.Xr Q_SCVAL 3 set control bits +.El +.Ss Functions which manipulate the combined integer/fractional data bits +.Cl +.Xr Q_IFRAWMASK 3 integer/fractional bitmask +.Xr Q_IFVALIMASK 3 value of integer bits +.Xr Q_IFVALFMASK 3 value of fractional bits +.Xr Q_GIFRAW 3 raw integer/fractional bits +.Xr Q_GIFABSVAL 3 absolute value of fractional bits +.Xr Q_GIFVAL 3 real value of fractional bits +.Xr Q_SIFVAL 3 set integer/fractional bits +.Xr Q_SIFVALS 3 set separate integer/fractional values +.El +.Ss Functions which manipulate the integer data bits +.Cl +.Xr Q_IRAWMASK 3 integer bitmask +.Xr Q_GIRAW 3 raw integer bits +.Xr Q_GIABSVAL 3 absolute value of integer bits +.Xr Q_GIVAL 3 real value of integer bits +.Xr Q_SIVAL 3 set integer bits +.El +.Ss Functions which manipulate the fractional data bits +.Cl +.Xr Q_FRAWMASK 3 fractional bitmask +.Xr Q_GFRAW 3 raw fractional bits +.Xr Q_GFABSVAL 3 absolute value of fractional bits +.Xr Q_GFVAL 3 real value of fractional bits +.Xr Q_SFVAL 3 set fractional bits +.El +.Ss Miscellaneous functions/variables +.Cl +.Xr Q_NCBITS 3 number of reserved control bits +.Xr Q_BT 3 C data type +.Xr Q_TC 3 casted data type +.Xr Q_NTBITS 3 number of total bits +.Xr Q_NFCBITS 3 number of control-encoded fractional bits +.Xr Q_MAXNFBITS 3 number of maximum fractional bits +.Xr Q_NFBITS 3 number of effective fractional bits +.Xr Q_NIBITS 3 number of integer bits +.Xr Q_RPSHFT 3 bit position of radix point +.Xr Q_ABS 3 absolute value +.Xr Q_MAXSTRLEN 3 number of characters to render string +.Xr Q_TOSTR 3 render string +.Xr Q_SHL 3 left-shifted value +.Xr Q_SHR 3 right-shifted value +.Xr Q_DEBUG 3 render debugging information +.Xr Q_DFV2BFV 3 convert decimal fractional value +.El +.Sh IMPLEMENTATION DETAILS +The +.Nm +data types and APIs support fixed-point math based on the +.Dq Q +number format. +This implementation uses the Q notation +.Em Qm.n , +where +.Em m +specifies the number of bits for integral data +.Pq excluding the sign bit for signed types , +and +.Em n +specifies the number of bits for fractional data. +.Pp +The APIs have been built around the following q_t derived data types: +.Bd -literal -offset indent +typedef int8_t s8q_t; +typedef uint8_t u8q_t; +typedef int16_t s16q_t; +typedef uint16_t u16q_t; +typedef int32_t s32q_t; +typedef uint32_t u32q_t; +typedef int64_t s64q_t; +typedef uint64_t u64q_t; +.Ed +.Pp +These types are referred to generically in the earlier API definitions as +.Fa QTYPE , +while +.Fa ITYPE +refers to the +.Xr stdint 7 +integer types the Q data types are derived from. +.Fa NTYPE +is used to refer to any numeric type and is therefore a superset of +.Fa QTYPE +and +.Fa ITYPE . +.Pp +The 3 least significant bits +.Pq LSBs +of all q_t data types are reserved for embedded control data: +.Bl -dash +.It +bits 1-2 specify the binary radix point shift index operand, with 00,01,10,11 == +1,2,3,4. +.It +bit 3 specifies the radix point shift index operand multiplier as 2 +.Pq 0 +or 16 +.Pq 1 . +.El +.Pp +This scheme can therefore represent Q numbers with +.Bq 2,4,6,8,16,32,48,64 +bits of precision after the binary radix point. +The number of bits available for the integral component is not explicitly +specified, and implicitly consumes the remaining available bits of the chosen Q +data type. +.Pp +Additionally, the most significant bit +.Pq MSB +of signed Q types stores the sign bit, with bit value 0 representing a positive +number and bit value 1 representing a negative number. +Negative numbers are stored as absolute values with the sign bit set, rather +than the more typical two's complement representation. +This avoids having to bit shift negative numbers, which can result in undefined +behaviour from some compilers. +.Pp +This binary representation used for Q numbers therefore comprises a set of +distinct data bit types and associated bit counts. +Data bit types/labels, listed in LSB to MSB order, are: control +.Sq C , +fractional +.Sq F , +integer +.Sq I +and sign +.Sq S . +The following example illustrates the binary representation of a Q20.8 number +represented using a s32q_t variable: +.Bd -literal -offset indent +M L +S S +B B + +3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 +1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 + +S I I I I I I I I I I I I I I I I I I I I F F F F F F F F C C C +.Ed +.Pp +Important bit counts are: total, control, control-encoded fractional, maximum +fractional, effective fractional and integer bits. +.Pp +The count of total bits is derived from the size of the q_t data type. +For example, a s32q_t has 32 total bits. +.Pp +The count of control-encoded fractional bits is derived from calculating the +number of fractional bits per the control bit encoding scheme. +For example, the control bits binary value of 101 encodes a fractional bit +count of 2 x 16 = 32 fractional bits. +.Pp +The count of maximum fractional bits is derived from the difference between the +counts of total bits and control/sign bits. +For example, a s32q_t has a maximum of 32 - 3 - 1 = 28 fractional bits. +.Pp +The count of effective fractional bits is derived from the minimum of the +control-encoded fractional bits and the maximum fractional bits. +For example, a s32q_t with 32 control-encoded fractional bits is effectively +limited to 28 fractional bits. +.Pp +The count of integer bits is derived from the difference between the counts of +total bits and all other non-integer data bits +.Pq the sum of control, fractional and sign bits. +For example, a s32q_t with 8 effective fractional bits has 32 - 3 - 8 - 1 = 20 integer +bits. +The count of integer bits can be zero if all available numeric data bits have +been reserved for fractional data, e.g., when the number of control-encoded +fractional bits is greater than or equal to the underlying Q data type's maximum +fractional bits. +.Sh EXAMPLES +.Ss Calculating area of a circle with r=4.2 and rpshft=16 +.Bd -literal -offset indent +u64q_t a, pi, r; +char buf[32] + +Q_INI(&a, 0, 0, 16); +Q_INI(&pi, 3, 14159, 16); +Q_INI(&r, 4, 2, 16); + +Q_QCLONEQ(&a, r); +Q_QMULQ(&a, r); +Q_QMULQ(&a, pi); + +Q_TOSTR(a, -1, 10, buf, sizeof(buf)); +printf("%s\\n", buf); +.Ed +.Ss Debugging +Declare a Q20.8 s32q_t number +.Fa s32 , +initialise it with the fixed-point value for 5/3, and render a debugging +representation of the variable +.Pq including its full precision decimal C-string representation , +to the console: +.Bd -literal -offset indent +s32q_t s32; +Q_INI(&s32, 0, 0, 8); +Q_QFRACI(&s32, 5, 3); +char buf[Q_MAXSTRLEN(s32, 10)]; +Q_TOSTR(s32, -1, 10, buf, sizeof(buf)); +printf(Q_DEBUG(s32, "", "\\n\\ttostr=%s\\n\\n", 0), buf); +.Ed +.Pp +The above code outputs the following to the console: +.Bd -literal -offset indent +"s32"@0x7fffffffe7d4 + type=s32q_t, Qm.n=Q20.8, rpshft=11, imin=0xfff00001, \\ +imax=0xfffff + qraw=0x00000d53 + imask=0x7ffff800, fmask=0x000007f8, cmask=0x00000007, \\ +ifmask=0x7ffffff8 + iraw=0x00000800, iabsval=0x1, ival=0x1 + fraw=0x00000550, fabsval=0xaa, fval=0xaa + tostr=1.664 +.Ed +.Pp +Note: The +.Qq \e +present in the rendered output above indicates a manual line break inserted to +keep the man page within 80 columns and is not part of the actual output. +.Sh SEE ALSO +.Xr errno 2 , +.Xr math 3 , +.Xr Q_FRAWMASK 3 , +.Xr Q_IFRAWMASK 3 , +.Xr Q_INI 3 , +.Xr Q_IRAWMASK 3 , +.Xr Q_QABS 3 , +.Xr Q_QADDI 3 , +.Xr Q_QADDQ 3 , +.Xr Q_SIGNED 3 , +.Xr Q_SIGNSHFT 3 , +.Xr stdint 7 +.Sh HISTORY +The +.Nm +functions first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +functions and this manual page were written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org +and sponsored by Netflix, Inc. diff --git a/static/freebsd/man3/queue.3 b/static/freebsd/man3/queue.3 new file mode 100644 index 00000000..535358ae --- /dev/null +++ b/static/freebsd/man3/queue.3 @@ -0,0 +1,1487 @@ +.\" Copyright (c) 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 28, 2025 +.Dt QUEUE 3 +.Os +.Sh NAME +.Nm SLIST_CLASS_ENTRY , +.Nm SLIST_CLASS_HEAD , +.Nm SLIST_CONCAT , +.Nm SLIST_EMPTY , +.Nm SLIST_EMPTY_ATOMIC , +.Nm SLIST_ENTRY , +.Nm SLIST_FIRST , +.Nm SLIST_FOREACH , +.Nm SLIST_FOREACH_FROM , +.Nm SLIST_FOREACH_FROM_SAFE , +.Nm SLIST_FOREACH_SAFE , +.Nm SLIST_HEAD , +.Nm SLIST_HEAD_INITIALIZER , +.Nm SLIST_INIT , +.Nm SLIST_INSERT_AFTER , +.Nm SLIST_INSERT_HEAD , +.Nm SLIST_NEXT , +.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 , +.Nm STAILQ_FOREACH_FROM , +.Nm STAILQ_FOREACH_FROM_SAFE , +.Nm STAILQ_FOREACH_SAFE , +.Nm STAILQ_HEAD , +.Nm STAILQ_HEAD_INITIALIZER , +.Nm STAILQ_INIT , +.Nm STAILQ_INSERT_AFTER , +.Nm STAILQ_INSERT_HEAD , +.Nm STAILQ_INSERT_TAIL , +.Nm STAILQ_LAST , +.Nm STAILQ_NEXT , +.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 , +.Nm LIST_FOREACH_FROM , +.Nm LIST_FOREACH_FROM_SAFE , +.Nm LIST_FOREACH_SAFE , +.Nm LIST_HEAD , +.Nm LIST_HEAD_INITIALIZER , +.Nm LIST_INIT , +.Nm LIST_INSERT_AFTER , +.Nm LIST_INSERT_BEFORE , +.Nm LIST_INSERT_HEAD , +.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 , +.Nm TAILQ_FOREACH_FROM , +.Nm TAILQ_FOREACH_FROM_SAFE , +.Nm TAILQ_FOREACH_REVERSE , +.Nm TAILQ_FOREACH_REVERSE_FROM , +.Nm TAILQ_FOREACH_REVERSE_FROM_SAFE , +.Nm TAILQ_FOREACH_REVERSE_SAFE , +.Nm TAILQ_FOREACH_SAFE , +.Nm TAILQ_HEAD , +.Nm TAILQ_HEAD_INITIALIZER , +.Nm TAILQ_INIT , +.Nm TAILQ_INSERT_AFTER , +.Nm TAILQ_INSERT_BEFORE , +.Nm TAILQ_INSERT_HEAD , +.Nm TAILQ_INSERT_TAIL , +.Nm TAILQ_LAST , +.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 +.Sh SYNOPSIS +.In sys/queue.h +.\" +.Fn SLIST_CLASS_ENTRY "CLASSTYPE" +.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" +.Fn SLIST_FOREACH_FROM "TYPE *var" "SLIST_HEAD *head" "SLIST_ENTRY NAME" +.Fn SLIST_FOREACH_FROM_SAFE "TYPE *var" "SLIST_HEAD *head" "SLIST_ENTRY NAME" "TYPE *temp_var" +.Fn SLIST_FOREACH_SAFE "TYPE *var" "SLIST_HEAD *head" "SLIST_ENTRY NAME" "TYPE *temp_var" +.Fn SLIST_HEAD "HEADNAME" "TYPE" +.Fn SLIST_HEAD_INITIALIZER "SLIST_HEAD head" +.Fn SLIST_INIT "SLIST_HEAD *head" +.Fn SLIST_INSERT_AFTER "TYPE *listelm" "TYPE *elm" "SLIST_ENTRY NAME" +.Fn SLIST_INSERT_HEAD "SLIST_HEAD *head" "TYPE *elm" "SLIST_ENTRY NAME" +.Fn SLIST_NEXT "TYPE *elm" "SLIST_ENTRY NAME" +.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" +.Fn STAILQ_FOREACH_FROM "TYPE *var" "STAILQ_HEAD *head" "STAILQ_ENTRY NAME" +.Fn STAILQ_FOREACH_FROM_SAFE "TYPE *var" "STAILQ_HEAD *head" "STAILQ_ENTRY NAME" "TYPE *temp_var" +.Fn STAILQ_FOREACH_SAFE "TYPE *var" "STAILQ_HEAD *head" "STAILQ_ENTRY NAME" "TYPE *temp_var" +.Fn STAILQ_HEAD "HEADNAME" "TYPE" +.Fn STAILQ_HEAD_INITIALIZER "STAILQ_HEAD head" +.Fn STAILQ_INIT "STAILQ_HEAD *head" +.Fn STAILQ_INSERT_AFTER "STAILQ_HEAD *head" "TYPE *listelm" "TYPE *elm" "STAILQ_ENTRY NAME" +.Fn STAILQ_INSERT_HEAD "STAILQ_HEAD *head" "TYPE *elm" "STAILQ_ENTRY NAME" +.Fn STAILQ_INSERT_TAIL "STAILQ_HEAD *head" "TYPE *elm" "STAILQ_ENTRY NAME" +.Fn STAILQ_LAST "STAILQ_HEAD *head" "TYPE *elm" "STAILQ_ENTRY NAME" +.Fn STAILQ_NEXT "TYPE *elm" "STAILQ_ENTRY NAME" +.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" +.Fn LIST_FOREACH_FROM "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" +.Fn LIST_FOREACH_FROM_SAFE "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" "TYPE *temp_var" +.Fn LIST_FOREACH_SAFE "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" "TYPE *temp_var" +.Fn LIST_HEAD "HEADNAME" "TYPE" +.Fn LIST_HEAD_INITIALIZER "LIST_HEAD head" +.Fn LIST_INIT "LIST_HEAD *head" +.Fn LIST_INSERT_AFTER "TYPE *listelm" "TYPE *elm" "LIST_ENTRY NAME" +.Fn LIST_INSERT_BEFORE "TYPE *listelm" "TYPE *elm" "LIST_ENTRY NAME" +.Fn LIST_INSERT_HEAD "LIST_HEAD *head" "TYPE *elm" "LIST_ENTRY NAME" +.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" +.Fn TAILQ_FOREACH_FROM "TYPE *var" "TAILQ_HEAD *head" "TAILQ_ENTRY NAME" +.Fn TAILQ_FOREACH_FROM_SAFE "TYPE *var" "TAILQ_HEAD *head" "TAILQ_ENTRY NAME" "TYPE *temp_var" +.Fn TAILQ_FOREACH_REVERSE "TYPE *var" "TAILQ_HEAD *head" "HEADNAME" "TAILQ_ENTRY NAME" +.Fn TAILQ_FOREACH_REVERSE_FROM "TYPE *var" "TAILQ_HEAD *head" "HEADNAME" "TAILQ_ENTRY NAME" +.Fn TAILQ_FOREACH_REVERSE_FROM_SAFE "TYPE *var" "TAILQ_HEAD *head" "HEADNAME" "TAILQ_ENTRY NAME" "TYPE *temp_var" +.Fn TAILQ_FOREACH_REVERSE_SAFE "TYPE *var" "TAILQ_HEAD *head" "HEADNAME" "TAILQ_ENTRY NAME" "TYPE *temp_var" +.Fn TAILQ_FOREACH_SAFE "TYPE *var" "TAILQ_HEAD *head" "TAILQ_ENTRY NAME" "TYPE *temp_var" +.Fn TAILQ_HEAD "HEADNAME" "TYPE" +.Fn TAILQ_HEAD_INITIALIZER "TAILQ_HEAD head" +.Fn TAILQ_INIT "TAILQ_HEAD *head" +.Fn TAILQ_INSERT_AFTER "TAILQ_HEAD *head" "TYPE *listelm" "TYPE *elm" "TAILQ_ENTRY NAME" +.Fn TAILQ_INSERT_BEFORE "TYPE *listelm" "TYPE *elm" "TAILQ_ENTRY NAME" +.Fn TAILQ_INSERT_HEAD "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME" +.Fn TAILQ_INSERT_TAIL "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME" +.Fn TAILQ_LAST "TAILQ_HEAD *head" "HEADNAME" +.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 +These macros define and operate on four types of data structures which +can be used in both C and C++ source code: +.Bl -enum -compact -offset indent +.It +Lists +.It +Singly-linked lists +.It +Singly-linked tail queues +.It +Tail queues +.El +All four structures support the following functionality: +.Bl -enum -compact -offset indent +.It +Insertion of a new entry at the head of the list. +.It +Insertion of a new entry after any element in the list. +.It +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 +Singly-linked lists are the simplest of the four data structures +and support only the above functionality. +Singly-linked lists are ideal for applications with large datasets +and few or no removals, +or for implementing a LIFO queue. +Singly-linked lists add the following functionality: +.Bl -enum -compact -offset indent +.It +O(n) removal of any entry in the list. +.It +O(n) concatenation of two lists. +.El +.Pp +Singly-linked tail queues add the following functionality: +.Bl -enum -compact -offset indent +.It +Entries can be added at the end of a list. +.It +O(n) removal of any entry in the list. +.It +They may be concatenated. +.El +However: +.Bl -enum -compact -offset indent +.It +All list insertions must specify the head of the list. +.It +Each head entry requires two pointers rather than one. +.It +Code size is about 15% greater and operations run about 20% slower +than singly-linked lists. +.El +.Pp +Singly-linked tail queues are ideal for applications with large datasets and +few or no removals, +or for implementing a FIFO queue. +.Pp +All doubly linked types of data structures (lists and tail queues) +additionally allow: +.Bl -enum -compact -offset indent +.It +Insertion of a new entry before any element in the list. +.It +O(1) removal of any entry in the list. +.El +However: +.Bl -enum -compact -offset indent +.It +Each element requires two pointers rather than one. +.It +Code size and execution time of operations (except for removal) is about +twice that of the singly-linked data-structures. +.El +.Pp +Linked lists are the simplest of the doubly linked data structures. +They add the following functionality over the above: +.Bl -enum -compact -offset indent +.It +O(n) concatenation of two lists. +.It +They may be traversed backwards. +.El +However: +.Bl -enum -compact -offset indent +.It +To traverse backwards, an entry to begin the traversal and the list in +which it is contained must be specified. +.El +.Pp +Tail queues add the following functionality: +.Bl -enum -compact -offset indent +.It +Entries can be added at the end of a list. +.It +They may be traversed backwards, from tail to head. +.It +They may be concatenated. +.El +However: +.Bl -enum -compact -offset indent +.It +All list insertions and removals must specify the head of the list. +.It +Each head entry requires two pointers rather than one. +.It +Code size is about 15% greater and operations run about 20% slower +than singly-linked lists. +.El +.Pp +In the macro definitions, +.Fa TYPE +is the name of a user defined structure. +The structure must contain a field called +.Fa NAME +which is of type +.Li SLIST_ENTRY , +.Li STAILQ_ENTRY , +.Li LIST_ENTRY , +or +.Li TAILQ_ENTRY . +In the macro definitions, +.Fa CLASSTYPE +is the name of a user defined class. +The class must contain a field called +.Fa NAME +which is of type +.Li SLIST_CLASS_ENTRY , +.Li STAILQ_CLASS_ENTRY , +.Li LIST_CLASS_ENTRY , +or +.Li TAILQ_CLASS_ENTRY . +The argument +.Fa HEADNAME +is the name of a user defined structure that must be declared +using the macros +.Li SLIST_HEAD , +.Li SLIST_CLASS_HEAD , +.Li STAILQ_HEAD , +.Li STAILQ_CLASS_HEAD , +.Li LIST_HEAD , +.Li LIST_CLASS_HEAD , +.Li TAILQ_HEAD , +or +.Li TAILQ_CLASS_HEAD . +See the examples below for further explanation of how these +macros are used. +.Sh SINGLY-LINKED LISTS +A singly-linked list is headed by a structure defined by the +.Nm SLIST_HEAD +macro. +This structure contains a single pointer to the first element +on the list. +The elements are singly linked for minimum space and pointer manipulation +overhead at the expense of O(n) removal for arbitrary elements. +New elements can be added to the list after an existing element or +at the head of the list. +An +.Fa SLIST_HEAD +structure is declared as follows: +.Bd -literal -offset indent +SLIST_HEAD(HEADNAME, TYPE) head; +.Ed +.Pp +where +.Fa HEADNAME +is the name of the structure to be defined, and +.Fa TYPE +is the type of the elements to be linked into the list. +A pointer to the head of the list can later be declared as: +.Bd -literal -offset indent +struct HEADNAME *headp; +.Ed +.Pp +(The names +.Li head +and +.Li headp +are user selectable.) +.Pp +The macro +.Nm SLIST_HEAD_INITIALIZER +evaluates to an initializer for the list +.Fa head . +.Pp +The macro +.Nm SLIST_CONCAT +concatenates the list headed by +.Fa head2 +onto the end of the one headed by +.Fa head1 +removing all entries from the former. +Use of this macro should be avoided as it traverses the entirety of the +.Fa head1 +list. +A singly-linked tail queue should be used if this macro is needed in +high-usage code paths or to operate on long lists. +.Pp +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 +declares a structure that connects the elements in +the list. +.Pp +The macro +.Nm SLIST_FIRST +returns the first element in the list or NULL if the list is empty. +.Pp +The macro +.Nm SLIST_FOREACH +traverses the list referenced by +.Fa head +in the forward direction, assigning each element in +turn to +.Fa var . +.Pp +The macro +.Nm SLIST_FOREACH_FROM +behaves identically to +.Nm SLIST_FOREACH +when +.Fa var +is NULL, else it treats +.Fa var +as a previously found SLIST element and begins the loop at +.Fa var +instead of the first element in the SLIST referenced by +.Fa head . +.Pp +The macro +.Nm SLIST_FOREACH_SAFE +traverses the list referenced by +.Fa head +in the forward direction, assigning each element in +turn to +.Fa var . +However, unlike +.Fn SLIST_FOREACH +here it is permitted to both remove +.Fa var +as well as free it from within the loop safely without interfering with the +traversal. +.Pp +The macro +.Nm SLIST_FOREACH_FROM_SAFE +behaves identically to +.Nm SLIST_FOREACH_SAFE +when +.Fa var +is NULL, else it treats +.Fa var +as a previously found SLIST element and begins the loop at +.Fa var +instead of the first element in the SLIST referenced by +.Fa head . +.Pp +The macro +.Nm SLIST_INIT +initializes the list referenced by +.Fa head . +.Pp +The macro +.Nm SLIST_INSERT_HEAD +inserts the new element +.Fa elm +at the head of the list. +.Pp +The macro +.Nm SLIST_INSERT_AFTER +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +The macro +.Nm SLIST_NEXT +returns the next element in the list. +.Pp +The macro +.Nm SLIST_REMOVE_AFTER +removes the element after +.Fa elm +from the list. +Unlike +.Fa SLIST_REMOVE , +this macro does not traverse the entire list. +.Pp +The macro +.Nm SLIST_REMOVE_HEAD +removes the element +.Fa elm +from the head of the list. +For optimum efficiency, +elements being removed from the head of the list should explicitly use +this macro instead of the generic +.Fa SLIST_REMOVE +macro. +.Pp +The macro +.Nm SLIST_REMOVE +removes the element +.Fa elm +from the list. +Use of this macro should be avoided as it traverses the entire list. +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 +and +.Fa head2 . +.Sh SINGLY-LINKED LIST EXAMPLE +.Bd -literal +SLIST_HEAD(slisthead, entry) head = + SLIST_HEAD_INITIALIZER(head); +struct slisthead *headp; /* Singly-linked List head. */ +struct entry { + ... + SLIST_ENTRY(entry) entries; /* Singly-linked List. */ + ... +} *n1, *n2, *n3, *np; + +SLIST_INIT(&head); /* Initialize the list. */ + +n1 = malloc(sizeof(struct entry)); /* Insert at the head. */ +SLIST_INSERT_HEAD(&head, n1, entries); + +n2 = malloc(sizeof(struct entry)); /* Insert after. */ +SLIST_INSERT_AFTER(n1, n2, entries); + +SLIST_REMOVE(&head, n2, entry, entries);/* Deletion. */ +free(n2); + +n3 = SLIST_FIRST(&head); +SLIST_REMOVE_HEAD(&head, entries); /* Deletion from the head. */ +free(n3); + /* Forward traversal. */ +SLIST_FOREACH(np, &head, entries) + np-> ... + /* Safe forward traversal. */ +SLIST_FOREACH_SAFE(np, &head, entries, np_temp) { + np->do_stuff(); + ... + SLIST_REMOVE(&head, np, entry, entries); + free(np); +} + +while (!SLIST_EMPTY(&head)) { /* List Deletion. */ + n1 = SLIST_FIRST(&head); + SLIST_REMOVE_HEAD(&head, entries); + free(n1); +} +.Ed +.Sh SINGLY-LINKED TAIL QUEUES +A singly-linked tail queue is headed by a structure defined by the +.Nm STAILQ_HEAD +macro. +This structure contains a pair of pointers, +one to the first element in the tail queue and the other to +the last element in the tail queue. +The elements are singly linked for minimum space and pointer +manipulation overhead at the expense of O(n) removal for arbitrary +elements. +New elements can be added to the tail queue after an existing element, +at the head of the tail queue, or at the end of the tail queue. +A +.Fa STAILQ_HEAD +structure is declared as follows: +.Bd -literal -offset indent +STAILQ_HEAD(HEADNAME, TYPE) head; +.Ed +.Pp +where +.Li HEADNAME +is the name of the structure to be defined, and +.Li TYPE +is the type of the elements to be linked into the tail queue. +A pointer to the head of the tail queue can later be declared as: +.Bd -literal -offset indent +struct HEADNAME *headp; +.Ed +.Pp +(The names +.Li head +and +.Li headp +are user selectable.) +.Pp +The macro +.Nm STAILQ_HEAD_INITIALIZER +evaluates to an initializer for the tail queue +.Fa head . +.Pp +The macro +.Nm STAILQ_CONCAT +concatenates the tail queue headed by +.Fa head2 +onto the end of the one headed by +.Fa head1 +removing all entries from the former. +.Pp +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 +declares a structure that connects the elements in +the tail queue. +.Pp +The macro +.Nm STAILQ_FIRST +returns the first item on the tail queue or NULL if the tail queue +is empty. +.Pp +The macro +.Nm STAILQ_FOREACH +traverses the tail queue referenced by +.Fa head +in the forward direction, assigning each element +in turn to +.Fa var . +.Pp +The macro +.Nm STAILQ_FOREACH_FROM +behaves identically to +.Nm STAILQ_FOREACH +when +.Fa var +is NULL, else it treats +.Fa var +as a previously found STAILQ element and begins the loop at +.Fa var +instead of the first element in the STAILQ referenced by +.Fa head . +.Pp +The macro +.Nm STAILQ_FOREACH_SAFE +traverses the tail queue referenced by +.Fa head +in the forward direction, assigning each element +in turn to +.Fa var . +However, unlike +.Fn STAILQ_FOREACH +here it is permitted to both remove +.Fa var +as well as free it from within the loop safely without interfering with the +traversal. +.Pp +The macro +.Nm STAILQ_FOREACH_FROM_SAFE +behaves identically to +.Nm STAILQ_FOREACH_SAFE +when +.Fa var +is NULL, else it treats +.Fa var +as a previously found STAILQ element and begins the loop at +.Fa var +instead of the first element in the STAILQ referenced by +.Fa head . +.Pp +The macro +.Nm STAILQ_INIT +initializes the tail queue referenced by +.Fa head . +.Pp +The macro +.Nm STAILQ_INSERT_HEAD +inserts the new element +.Fa elm +at the head of the tail queue. +.Pp +The macro +.Nm STAILQ_INSERT_TAIL +inserts the new element +.Fa elm +at the end of the tail queue. +.Pp +The macro +.Nm STAILQ_INSERT_AFTER +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +The macro +.Nm STAILQ_LAST +returns the last item on the tail queue. +If the tail queue is empty the return value is +.Dv NULL . +.Pp +The macro +.Nm STAILQ_NEXT +returns the next item on the tail queue, or NULL this item is the last. +.Pp +The macro +.Nm STAILQ_REMOVE_AFTER +removes the element after +.Fa elm +from the tail queue. +Unlike +.Fa STAILQ_REMOVE , +this macro does not traverse the entire tail queue. +.Pp +The macro +.Nm STAILQ_REMOVE_HEAD +removes the element at the head of the tail queue. +For optimum efficiency, +elements being removed from the head of the tail queue should +use this macro explicitly rather than the generic +.Fa STAILQ_REMOVE +macro. +.Pp +The macro +.Nm STAILQ_REMOVE +removes the element +.Fa elm +from the tail queue. +Use of this macro should be avoided as it traverses the entire list. +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 +and +.Fa head2 . +.Sh SINGLY-LINKED TAIL QUEUE EXAMPLE +.Bd -literal +STAILQ_HEAD(stailhead, entry) head = + STAILQ_HEAD_INITIALIZER(head); +struct stailhead *headp; /* Singly-linked tail queue head. */ +struct entry { + ... + STAILQ_ENTRY(entry) entries; /* Tail queue. */ + ... +} *n1, *n2, *n3, *np; + +STAILQ_INIT(&head); /* Initialize the queue. */ + +n1 = malloc(sizeof(struct entry)); /* Insert at the head. */ +STAILQ_INSERT_HEAD(&head, n1, entries); + +n1 = malloc(sizeof(struct entry)); /* Insert at the tail. */ +STAILQ_INSERT_TAIL(&head, n1, entries); + +n2 = malloc(sizeof(struct entry)); /* Insert after. */ +STAILQ_INSERT_AFTER(&head, n1, n2, entries); + /* Deletion. */ +STAILQ_REMOVE(&head, n2, entry, entries); +free(n2); + /* Deletion from the head. */ +n3 = STAILQ_FIRST(&head); +STAILQ_REMOVE_HEAD(&head, entries); +free(n3); + /* Forward traversal. */ +STAILQ_FOREACH(np, &head, entries) + np-> ... + /* Safe forward traversal. */ +STAILQ_FOREACH_SAFE(np, &head, entries, np_temp) { + np->do_stuff(); + ... + STAILQ_REMOVE(&head, np, entry, entries); + free(np); +} + /* TailQ Deletion. */ +while (!STAILQ_EMPTY(&head)) { + n1 = STAILQ_FIRST(&head); + STAILQ_REMOVE_HEAD(&head, entries); + free(n1); +} + /* Faster TailQ Deletion. */ +n1 = STAILQ_FIRST(&head); +while (n1 != NULL) { + n2 = STAILQ_NEXT(n1, entries); + free(n1); + n1 = n2; +} +STAILQ_INIT(&head); +.Ed +.Sh LISTS +A list is headed by a structure defined by the +.Nm LIST_HEAD +macro. +This structure contains a single pointer to the first element +on the list. +The elements are doubly linked so that an arbitrary element can be +removed without traversing the list. +New elements can be added to the list after an existing element, +before an existing element, or at the head of the list. +A +.Fa LIST_HEAD +structure is declared as follows: +.Bd -literal -offset indent +LIST_HEAD(HEADNAME, TYPE) head; +.Ed +.Pp +where +.Fa HEADNAME +is the name of the structure to be defined, and +.Fa TYPE +is the type of the elements to be linked into the list. +A pointer to the head of the list can later be declared as: +.Bd -literal -offset indent +struct HEADNAME *headp; +.Ed +.Pp +(The names +.Li head +and +.Li headp +are user selectable.) +.Pp +The macro +.Nm LIST_HEAD_INITIALIZER +evaluates to an initializer for the list +.Fa head . +.Pp +The macro +.Nm LIST_CONCAT +concatenates the list headed by +.Fa head2 +onto the end of the one headed by +.Fa head1 +removing all entries from the former. +Use of this macro should be avoided as it traverses the entirety of the +.Fa head1 +list. +A tail queue should be used if this macro is needed in +high-usage code paths or to operate on long lists. +.Pp +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 +declares a structure that connects the elements in +the list. +.Pp +The macro +.Nm LIST_FIRST +returns the first element in the list or NULL if the list +is empty. +.Pp +The macro +.Nm LIST_FOREACH +traverses the list referenced by +.Fa head +in the forward direction, assigning each element in turn to +.Fa var . +.Pp +The macro +.Nm LIST_FOREACH_FROM +behaves identically to +.Nm LIST_FOREACH +when +.Fa var +is NULL, else it treats +.Fa var +as a previously found LIST element and begins the loop at +.Fa var +instead of the first element in the LIST referenced by +.Fa head . +.Pp +The macro +.Nm LIST_FOREACH_SAFE +traverses the list referenced by +.Fa head +in the forward direction, assigning each element in turn to +.Fa var . +However, unlike +.Fn LIST_FOREACH +here it is permitted to both remove +.Fa var +as well as free it from within the loop safely without interfering with the +traversal. +.Pp +The macro +.Nm LIST_FOREACH_FROM_SAFE +behaves identically to +.Nm LIST_FOREACH_SAFE +when +.Fa var +is NULL, else it treats +.Fa var +as a previously found LIST element and begins the loop at +.Fa var +instead of the first element in the LIST referenced by +.Fa head . +.Pp +The macro +.Nm LIST_INIT +initializes the list referenced by +.Fa head . +.Pp +The macro +.Nm LIST_INSERT_HEAD +inserts the new element +.Fa elm +at the head of the list. +.Pp +The macro +.Nm LIST_INSERT_AFTER +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +The macro +.Nm LIST_INSERT_BEFORE +inserts the new element +.Fa elm +before the element +.Fa listelm . +.Pp +The macro +.Nm LIST_NEXT +returns the next element in the list, or NULL if this is the last. +.Pp +The macro +.Nm LIST_PREV +returns the previous element in the list, or NULL if this is the first. +List +.Fa head +must contain element +.Fa elm . +.Pp +The macro +.Nm LIST_REMOVE +removes the element +.Fa elm +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 +and +.Fa head2 . +.Sh LIST EXAMPLE +.Bd -literal +LIST_HEAD(listhead, entry) head = + LIST_HEAD_INITIALIZER(head); +struct listhead *headp; /* List head. */ +struct entry { + ... + LIST_ENTRY(entry) entries; /* List. */ + ... +} *n1, *n2, *n3, *np, *np_temp; + +LIST_INIT(&head); /* Initialize the list. */ + +n1 = malloc(sizeof(struct entry)); /* Insert at the head. */ +LIST_INSERT_HEAD(&head, n1, entries); + +n2 = malloc(sizeof(struct entry)); /* Insert after. */ +LIST_INSERT_AFTER(n1, n2, entries); + +n3 = malloc(sizeof(struct entry)); /* Insert before. */ +LIST_INSERT_BEFORE(n2, n3, entries); + +LIST_REMOVE(n2, entries); /* Deletion. */ +free(n2); + /* Forward traversal. */ +LIST_FOREACH(np, &head, entries) + np-> ... + + /* Safe forward traversal. */ +LIST_FOREACH_SAFE(np, &head, entries, np_temp) { + np->do_stuff(); + ... + LIST_REMOVE(np, entries); + free(np); +} + +while (!LIST_EMPTY(&head)) { /* List Deletion. */ + n1 = LIST_FIRST(&head); + LIST_REMOVE(n1, entries); + free(n1); +} + +n1 = LIST_FIRST(&head); /* Faster List Deletion. */ +while (n1 != NULL) { + n2 = LIST_NEXT(n1, entries); + free(n1); + n1 = n2; +} +LIST_INIT(&head); +.Ed +.Sh TAIL QUEUES +A tail queue is headed by a structure defined by the +.Nm TAILQ_HEAD +macro. +This structure contains a pair of pointers, +one to the first element in the tail queue and the other to +the last element in the tail queue. +The elements are doubly linked so that an arbitrary element can be +removed without traversing the tail queue. +New elements can be added to the tail queue after an existing element, +before an existing element, at the head of the tail queue, +or at the end of the tail queue. +A +.Fa TAILQ_HEAD +structure is declared as follows: +.Bd -literal -offset indent +TAILQ_HEAD(HEADNAME, TYPE) head; +.Ed +.Pp +where +.Li HEADNAME +is the name of the structure to be defined, and +.Li TYPE +is the type of the elements to be linked into the tail queue. +A pointer to the head of the tail queue can later be declared as: +.Bd -literal -offset indent +struct HEADNAME *headp; +.Ed +.Pp +(The names +.Li head +and +.Li headp +are user selectable.) +.Pp +The macro +.Nm TAILQ_HEAD_INITIALIZER +evaluates to an initializer for the tail queue +.Fa head . +.Pp +The macro +.Nm TAILQ_CONCAT +concatenates the tail queue headed by +.Fa head2 +onto the end of the one headed by +.Fa head1 +removing all entries from the former. +.Pp +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 +declares a structure that connects the elements in +the tail queue. +.Pp +The macro +.Nm TAILQ_FIRST +returns the first item on the tail queue or NULL if the tail queue +is empty. +.Pp +The macro +.Nm TAILQ_FOREACH +traverses the tail queue referenced by +.Fa head +in the forward direction, assigning each element in turn to +.Fa var . +.Fa var +is set to +.Dv NULL +if the loop completes normally, or if there were no elements. +.Pp +The macro +.Nm TAILQ_FOREACH_FROM +behaves identically to +.Nm TAILQ_FOREACH +when +.Fa var +is NULL, else it treats +.Fa var +as a previously found TAILQ element and begins the loop at +.Fa var +instead of the first element in the TAILQ referenced by +.Fa head . +.Pp +The macro +.Nm TAILQ_FOREACH_REVERSE +traverses the tail queue referenced by +.Fa head +in the reverse direction, assigning each element in turn to +.Fa var . +.Pp +The macro +.Nm TAILQ_FOREACH_REVERSE_FROM +behaves identically to +.Nm TAILQ_FOREACH_REVERSE +when +.Fa var +is NULL, else it treats +.Fa var +as a previously found TAILQ element and begins the reverse loop at +.Fa var +instead of the last element in the TAILQ referenced by +.Fa head . +.Pp +The macros +.Nm TAILQ_FOREACH_SAFE +and +.Nm TAILQ_FOREACH_REVERSE_SAFE +traverse the list referenced by +.Fa head +in the forward or reverse direction respectively, +assigning each element in turn to +.Fa var . +However, unlike their unsafe counterparts, +.Nm TAILQ_FOREACH +and +.Nm TAILQ_FOREACH_REVERSE +permit to both remove +.Fa var +as well as free it from within the loop safely without interfering with the +traversal. +.Pp +The macro +.Nm TAILQ_FOREACH_FROM_SAFE +behaves identically to +.Nm TAILQ_FOREACH_SAFE +when +.Fa var +is NULL, else it treats +.Fa var +as a previously found TAILQ element and begins the loop at +.Fa var +instead of the first element in the TAILQ referenced by +.Fa head . +.Pp +The macro +.Nm TAILQ_FOREACH_REVERSE_FROM_SAFE +behaves identically to +.Nm TAILQ_FOREACH_REVERSE_SAFE +when +.Fa var +is NULL, else it treats +.Fa var +as a previously found TAILQ element and begins the reverse loop at +.Fa var +instead of the last element in the TAILQ referenced by +.Fa head . +.Pp +The macro +.Nm TAILQ_INIT +initializes the tail queue referenced by +.Fa head . +.Pp +The macro +.Nm TAILQ_INSERT_HEAD +inserts the new element +.Fa elm +at the head of the tail queue. +.Pp +The macro +.Nm TAILQ_INSERT_TAIL +inserts the new element +.Fa elm +at the end of the tail queue. +.Pp +The macro +.Nm TAILQ_INSERT_AFTER +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +The macro +.Nm TAILQ_INSERT_BEFORE +inserts the new element +.Fa elm +before the element +.Fa listelm . +.Pp +The macro +.Nm TAILQ_LAST +returns the last item on the tail queue. +If the tail queue is empty the return value is +.Dv NULL . +.Pp +The macro +.Nm TAILQ_NEXT +returns the next item on the tail queue, or NULL if this item is the last. +.Pp +The macro +.Nm TAILQ_PREV +returns the previous item on the tail queue, or NULL if this item +is the first. +.Pp +The macro +.Nm TAILQ_REMOVE +removes the element +.Fa elm +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 +and +.Fa head2 . +.Sh TAIL QUEUE EXAMPLE +.Bd -literal +TAILQ_HEAD(tailhead, entry) head = + TAILQ_HEAD_INITIALIZER(head); +struct tailhead *headp; /* Tail queue head. */ +struct entry { + ... + TAILQ_ENTRY(entry) entries; /* Tail queue. */ + ... +} *n1, *n2, *n3, *n4, *np; + +TAILQ_INIT(&head); /* Initialize the queue. */ + +n1 = malloc(sizeof(struct entry)); /* Insert at the head. */ +TAILQ_INSERT_HEAD(&head, n1, entries); + +n1 = malloc(sizeof(struct entry)); /* Insert at the tail. */ +TAILQ_INSERT_TAIL(&head, n1, entries); + +n2 = malloc(sizeof(struct entry)); /* Insert after. */ +TAILQ_INSERT_AFTER(&head, n1, n2, entries); + +n3 = malloc(sizeof(struct entry)); /* Insert before. */ +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-> ... + /* Safe forward traversal. */ +TAILQ_FOREACH_SAFE(np, &head, entries, np_temp) { + np->do_stuff(); + ... + TAILQ_REMOVE(&head, np, entries); + free(np); +} + /* Reverse traversal. */ +TAILQ_FOREACH_REVERSE(np, &head, tailhead, entries) + np-> ... + /* TailQ Deletion. */ +while (!TAILQ_EMPTY(&head)) { + n1 = TAILQ_FIRST(&head); + TAILQ_REMOVE(&head, n1, entries); + free(n1); +} + /* Faster TailQ Deletion. */ +n1 = TAILQ_FIRST(&head); +while (n1 != NULL) { + n2 = TAILQ_NEXT(n1, entries); + free(n1); + n1 = n2; +} +TAILQ_INIT(&head); +.Ed +.Sh DIAGNOSTICS +.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 +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 element +.Fa elm , +which must directly follow the element whose +.Va &SLIST_NEXT() +is +.Fa prev , +from the list. +This macro may insert, under conditions detailed above, check code that +validates that +.Fa elm +indeed follows +.Fa prev +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 +.Sh HISTORY +The +.Nm queue +functions first appeared in +.Bx 4.4 . diff --git a/static/freebsd/man3/sigevent.3 b/static/freebsd/man3/sigevent.3 new file mode 100644 index 00000000..731b3658 --- /dev/null +++ b/static/freebsd/man3/sigevent.3 @@ -0,0 +1,129 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2016 John H. Baldwin <jhb@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 February 25, 2020 +.Dt SIGEVENT 3 +.Os +.Sh NAME +.Nm sigevent +.Nd "asynchronous event notification" +.Sh SYNOPSIS +.In signal.h +.Sh DESCRIPTION +Some operations permit threads to request asynchronous notification of events +via a +.Vt struct sigevent +structure. +This structure contains several fields that describe the requested notification: +.Bl -column ".Vt void (*)(union sigval)" ".Va sigev_notify_kevent_flags" +.It Sy Type Ta Sy Member Ta Sy Description +.It Vt int Ta sigev_notify Ta notification method +.It Vt int Ta sigev_signo Ta signal number +.It Vt union sigval Ta sigev_value Ta signal value +.It Vt int Ta sigev_notify_kqueue Ta +.Xr kqueue 2 +file descriptor +.It Vt unsigned short Ta sigev_notify_kevent_flags Ta kevent flags +.It Vt lwpid_t Ta sigev_notify_thread_id Ta LWP ID +.It Vt void (*)(union sigval) Ta sigev_notify_function Ta +callback function pointer +.It Vt pthread_attr_t * Ta sigev_notify_attributes Ta +callback thread attributes +.El +.Pp +The +.Va sigev_notify +field specifies the notification method used when the event triggers: +.Bl -tag -width ".Dv SIGEV_THREAD_ID" +.It Dv SIGEV_NONE +No notification is sent. +.It Dv SIGEV_SIGNAL +The signal +.Va sigev_signo +is queued as a real-time signal to the calling process. +The value stored in +.Va sigev_value +will be present in the +.Va si_value +of the +.Vt siginfo_t +structure of the queued signal. +.It Dv SIGEV_THREAD +The notification function in +.Va sigev_notify_function +is called in a separate thread context. +The thread is created with the attributes specified in +.Va *sigev_notify_attributes . +The value stored in +.Va sigev_value +is passed as the sole argument to +.Va sigev_notify_function . +If +.Va sigev_notify_attributes +is +.Dv NULL , +the thread is created with default attributes. +.It Dv SIGEV_KEVENT +A new kevent is posted to the kqueue +.Va sigev_notify_kqueue . +The +.Va udata +member of the kevent structure contains the value stored in +.Va sigev_value . +The meaning of other fields in the kevent are specific to the type of triggered +event. +.It Dv SIGEV_THREAD_ID +The signal +.Va sigev_signo +is queued to the thread whose LWP ID is +.Va sigev_notify_thread_id . +The value stored in +.Va sigev_value +will be present in the +.Va si_value +of the +.Vt siginfo_t +structure of the queued signal. +.El +.Sh NOTES +Note that programs wishing to use +.Dv SIGEV_THREAD +notifications must link against the +.Lb librt . +.Sh SEE ALSO +.Xr aio_read 2 , +.Xr mq_notify 2 , +.Xr timer_create 2 , +.Xr siginfo 3 +.Sh STANDARDS +The +.Vt struct sigevent +type conforms to +.St -p1003.1-2004 . +.Sh HISTORY +The +.Va sigevent +structure first appeared in +.Fx 3.3 . diff --git a/static/freebsd/man3/siginfo.3 b/static/freebsd/man3/siginfo.3 new file mode 100644 index 00000000..59e3ecf8 --- /dev/null +++ b/static/freebsd/man3/siginfo.3 @@ -0,0 +1,348 @@ +.\" Copyright (c) 2005 David Xu <davidxu@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(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 February 17, 2021 +.Dt SIGINFO 3 +.Os +.Sh NAME +.Nm siginfo +.Nd "signal generation information" +.Sh SYNOPSIS +.In signal.h +.Sh DESCRIPTION +A process may request signal information when it is catching a signal. +The information specifies why the system generated that signal. +To request signal information in a signal handler, the user can set +.Dv SA_SIGINFO +in +.Va sa_flags +before +.Xr sigaction 2 +is called, +otherwise the user can use +.Xr sigwaitinfo 2 +and +.Xr sigtimedwait 2 +to get signal information. +In either case, the system returns the information in a structure of type +.Vt siginfo_t , +which includes the following information: +.Bl -column ".Vt union signal" ".Va si_overrun" +.It Sy Type Ta Sy Member Ta Sy Description +.It Vt int Ta Va si_signo Ta +signal number +.It Vt int Ta Va si_errno Ta +error number +.It Vt int Ta Va si_code Ta +signal code +.It Vt union sigval Ta Va si_value Ta +signal value +.It Vt pid_t Ta Va si_pid Ta +sending process ID +.It Vt uid_t Ta Va si_uid Ta +sending process's real user ID +.It Vt void Ta Va *si_addr Ta +virtual address +.It Vt int Ta Va si_status Ta +exit value or signal +.It Vt long Ta Va si_band Ta +band event for +.Dv SIGPOLL +.It Vt int Ta Va si_trapno Ta +machine trap code +.It Vt int Ta Va si_timerid Ta +.Tn POSIX +timer ID +.It Vt int Ta Va si_overrun Ta +.Tn POSIX +timer overrun count +.It Vt int Ta Va si_mqd Ta +.Tn POSIX +message queue ID +.It Vt int Ta Va si_syscall Ta +system-call number for system calls blocked by Capsicum +.El +.Pp +The +.Va si_signo +member contains the signal number. +.Pp +The +.Va si_errno +member contains an error number defined in the file +.In errno.h . +.Pp +The +.Va si_code +member contains a code which describes the cause of the signal. +The macros specified in the +.Sy Code +column of the following table are defined +for use as values of +.Va si_code +that are signal-specific or non-signal-specific reasons why the signal was +generated: +.Bl -column ".Dv SIGPOLL" ".Dv CLD_CONTINUED" +.It Sy Signal Ta Sy Code Ta Sy Reason +.It Dv SIGILL Ta Dv ILL_ILLOPC Ta +illegal opcode +.It Ta Dv ILL_ILLOPN Ta +illegal operand +.It Ta Dv ILL_ILLADR Ta +illegal addressing mode +.It Ta Dv ILL_ILLTRP Ta +illegal trap +.It Ta Dv ILL_PRVOPC Ta +illegal privileged opcode +.It Ta Dv ILL_PRVREG Ta +illegal privileged register +.It Ta Dv ILL_COPROC Ta +coprocessor error +.It Ta Dv ILL_BADSTK Ta +internal stack error +.It Dv SIGFPE Ta Dv FPE_INTDIV Ta +integer divide by zero +.It Ta Dv FPE_INTOVF Ta +integer overflow +.It Ta Dv FPE_FLTDIV Ta +floating-point divide by zero +.It Ta Dv FPE_FLTOVF Ta +floating-point overflow +.It Ta Dv FPE_FLTUND Ta +floating-point underflow +.It Ta Dv FPE_FLTRES Ta +floating-point inexact result +.It Ta Dv FPE_FLTINV Ta +invalid floating-point operation +.It Ta Dv FPE_FLTSUB Ta +subscript out of range +.It Dv SIGSEGV Ta Dv SEGV_MAPERR Ta +address not mapped to object +.It Ta Dv SEGV_ACCERR Ta +invalid permissions for mapped object +.It Dv SIGBUS Ta Dv BUS_ADRALN Ta +invalid address alignment +.It Ta Dv BUS_ADRERR Ta +nonexistent physical address +.It Ta Dv BUS_OBJERR Ta +object-specific hardware error +.It Ta Dv BUS_OOMERR Ta +cannot alloc a page to map at fault +.It Dv SIGTRAP Ta Dv TRAP_BRKPT Ta +process breakpoint +.It Ta Dv TRAP_TRACE Ta +process trace trap +.It Ta Dv TRAP_DTRACE Ta +DTrace induced trap +.It Ta Dv TRAP_CAP Ta +capabilities protective trap +.It Dv SIGCHLD Ta Dv CLD_EXITED Ta +child has exited +.It Ta Dv CLD_KILLED Ta +child has terminated abnormally and did not create a core file +.It Ta Dv CLD_DUMPED Ta +child has terminated abnormally and created a core file +.It Ta Dv CLD_TRAPPED Ta +traced child has trapped +.It Ta Dv CLD_STOPPED Ta +child has stopped +.It Ta Dv CLD_CONTINUED Ta +stopped child has continued +.It Dv SIGPOLL Ta Dv POLL_IN Ta +data input available +.It Ta Dv POLL_OUT Ta +output buffers available +.It Ta Dv POLL_MSG Ta +input message available +.It Ta Dv POLL_ERR Ta +I/O error +.It Ta Dv POLL_PRI Ta +high priority input available +.It Ta Dv POLL_HUP Ta +device disconnected +.It Any Ta Dv SI_NOINFO Ta +Only the +.Va si_signo +member is meaningful; the value of all other members is unspecified. +.It Ta Dv SI_USER Ta +signal sent by +.Xr kill 2 +.It Ta Dv SI_QUEUE Ta +signal sent by +.Xr sigqueue 2 +.It Ta Dv SI_TIMER Ta +signal generated by expiration of a timer set by +.Xr timer_settime 2 +.It Ta Dv SI_ASYNCIO Ta +signal generated by completion of an asynchronous I/O request +.It Ta Dv SI_MESGQ Ta +signal generated by arrival of a message on an empty message queue +.It Ta Dv SI_KERNEL Ta +signal generated by miscellaneous parts of the kernel +.It Ta Dv SI_LWP Ta +signal sent by +.Xr pthread_kill 3 +.El +.Pp +For synchronous signals, +.Va si_addr +is generally set to the address of the faulting instruction. +However, synchronous signals raised by a faulting memory access such as +.Dv SIGSEGV +and +.Dv SIGBUS +may report the address of the faulting memory access (if available) in +.Va si_addr +instead. +Additionally +.Dv SIGTRAP +raised by a hardware watchpoint exception may report the data address that +triggered the watchpoint in +.Va si_addr . +.Pp +Synchronous signals set +.Va si_trapno +to a machine-dependent trap number. +.Pp +In addition, the following signal-specific information is available: +.Bl -column ".Dv SIGPOLL" ".Dv CLD_CONTINUED" +.It Sy Signal Ta Sy Member Ta Sy Value +.It Dv SIGCHLD Ta Va si_pid Ta +child process ID +.It Ta Va si_status Ta +exit value or signal; if +.Va si_code +is equal to +.Dv CLD_EXITED , +then it is equal to the exit value of the child process, otherwise, +it is equal to a signal that caused the child process to change state. +.It Ta Va si_uid Ta "real user ID of the process that sent the signal" +.It Dv SIGPOLL Ta Va si_band Ta "band event for" +.Dv POLL_IN , POLL_OUT , +or +.Dv POLL_MSG +.El +.Pp +Finally, the following code-specific information is available: +.Bl -column ".Dv SI_ASYNCIO" ".Va si_overrun" +.It Sy Code Ta Sy Member Ta Sy Value +.It Dv SI_USER Ta Va si_pid Ta +the process ID that sent the signal +.It Ta Va si_uid Ta +real user ID of the process that sent the signal +.It Dv SI_QUEUE Ta Va si_value Ta +the value passed to +.Xr sigqueue 2 +system call +.It Ta Va si_pid Ta +the process ID that sent the signal +.It Ta Va si_uid Ta +real user ID of the process that sent the signal +.It Dv SI_TIMER Ta Va si_value Ta +the value passed to +.Xr timer_create 2 +system call +.It Ta Va si_timerid Ta +the timer ID returned by +.Xr timer_create 2 +system call +.It Ta Va si_overrun Ta +timer overrun count corresponding to the signal +.It Ta Va si_errno Ta +If timer overrun will be +.Brq Dv DELAYTIMER_MAX , +an error code defined in +.In errno.h +is set +.It Dv SI_ASYNCIO Ta Va si_value Ta +the value passed to aio system calls +.It Dv SI_MESGQ Ta Va si_value Ta +the value passed to +.Xr mq_notify 2 +system call +.It Ta Va si_mqd Ta +the ID of the message queue which generated the signal +.It Dv SI_LWP Ta Va si_pid Ta +the process ID that sent the signal +.It Ta Va si_uid Ta +real user ID of the process that sent the signal +.El +.Sh NOTES +Currently, the kernel never generates the +.Dv SIGPOLL +signal. +.Dv SIGCHLD +signal is queued when a process changed its status or exited. +.Tn POSIX +Realtime Extensions like aio, timer, and message queue also queue +signals. +Signals with code +.Dv SI_USER , +.Dv SI_KERNEL +or +.Dv SI_LWP +are only queued if there are sufficient resources; +otherwise, +.Dv SI_NOINFO +results. +For some hardware architectures, the exact value of +.Va si_addr +might not be available. +.Sh SEE ALSO +.Xr aio_read 2 , +.Xr kill 2 , +.Xr mq_notify 2 , +.Xr sigaction 2 , +.Xr sigqueue 2 , +.Xr sigwaitinfo 2 , +.Xr timer_create 2 , +.Xr timer_settime 2 , +.Xr waitpid 2 , +.Xr pthread_kill 3 +.Sh STANDARDS +The +.Vt siginfo_t +type conforms to +.St -p1003.1-2004 . +.Sh HISTORY +Full support for +.Tn POSIX +signal information first appeared in +.Fx 7.0 . +The codes +.Dv SI_USER +and +.Dv SI_KERNEL +can be generated as of +.Fx 8.1 . +The code +.Dv SI_LWP +can be generated as of +.Fx 9.0 . +.Sh AUTHORS +This manual page was written by +.An David Xu Aq Mt davidxu@FreeBSD.org . diff --git a/static/freebsd/man3/snl.3 b/static/freebsd/man3/snl.3 new file mode 100644 index 00000000..04bae466 --- /dev/null +++ b/static/freebsd/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/static/freebsd/man3/stats.3 b/static/freebsd/man3/stats.3 new file mode 100644 index 00000000..7fe1fa61 --- /dev/null +++ b/static/freebsd/man3/stats.3 @@ -0,0 +1,966 @@ +.\" +.\" Copyright (c) 2016-2018 Netflix, Inc. +.\" 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, +.\" without modification, immediately at the beginning of the file. +.\" 2. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR +.\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd December 2, 2019 +.Dt STATS 3 +.Os +.Sh NAME +.Nm stats +.Nd statistics gathering +.Sh LIBRARY +.Lb libstats +.Sh SYNOPSIS +.In sys/arb.h +.In sys/qmath.h +.In sys/stats.h +.Ss Stats Blob Template Management Functions +.Ft int +.Fo stats_tpl_alloc +.Fa "const char *name" +.Fa "uint32_t flags" +.Fc +.Ft int +.Fo stats_tpl_fetch_allocid +.Fa "const char *name" +.Fa "uint32_t hash" +.Fc +.Ft int +.Fo stats_tpl_fetch +.Fa "int tpl_id" +.Fa "struct statsblob_tpl **tpl" +.Fc +.Ft int +.Fo stats_tpl_id2name +.Fa "uint32_t tpl_id" +.Fa "char *buf" +.Fa "size_t len" +.Fc +.Ft int +.Fo stats_tpl_sample_rates +.Fa "SYSCTL_HANDLER_ARGS" +.Fc +.Ft int +.Fo stats_tpl_sample_rollthedice +.Fa "struct stats_tpl_sample_rate *rates" +.Fa "int nrates" +.Fa "void *seed_bytes" +.Fa "size_t seed_len" +.Fc +.Ft struct voistatspec +.Fo STATS_VSS_SUM +.Fc +.Ft struct voistatspec +.Fo STATS_VSS_MAX +.Fc +.Ft struct voistatspec +.Fo STATS_VSS_MIN +.Fc +.Ft struct voistatspec +.Fo STATS_VSS_CRHIST<32|64>_LIN +.Fa "lb" +.Fa "ub" +.Fa "stepinc" +.Fa "vsdflags" +.Fc +.Ft struct voistatspec +.Fo STATS_VSS_CRHIST<32|64>_EXP +.Fa "lb" +.Fa "ub" +.Fa "stepbase" +.Fa "stepexp" +.Fa "vsdflags" +.Fc +.Ft struct voistatspec +.Fo "STATS_VSS_CRHIST<32|64>_LINEXP" +.Fa "lb" +.Fa "ub" +.Fa "nlinsteps" +.Fa "stepbase" +.Fa "vsdflags" +.Fc +.Ft struct voistatspec +.Fo "STATS_VSS_CRHIST<32|64>_USR" +.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" ) , "..." , +.Fa "vsdflags" +.Fc +.Ft struct voistatspec +.Fo "STATS_VSS_DVHIST<32|64>_USR" +.Fa Sy "HBKTS" Ns Pq Sy "DVBKT" Ns ( Em "val" ) , "..." , +.Fa "vsdflags" +.Fc +.Ft struct voistatspec +.Fo STATS_VSS_TDGSTCLUST<32|64> +.Fa "nctroids" +.Fa "prec" +.Fc +.Ft int +.Fo stats_tpl_add_voistats +.Fa "uint32_t tpl_id" +.Fa "int32_t voi_id" +.Fa "const char *voi_name" +.Fa "enum vsd_dtype voi_dtype" +.Fa "uint32_t nvss" +.Fa "struct voistatspec *vss" +.Fa "uint32_t flags" +.Fc +.Ss Stats Blob Data Gathering Functions +.Ft int +.Fo stats_voi_update_<abs|rel>_<dtype> +.Fa "struct statsblob *sb" +.Fa "int32_t voi_id" +.Fa "<dtype> voival" +.Fc +.Ss Stats Blob Utility Functions +.Ft struct statsblob * +.Fo stats_blob_alloc +.Fa "uint32_t tpl_id" +.Fa "uint32_t flags" +.Fc +.Ft int +.Fo stats_blob_init +.Fa "struct statsblob *sb" +.Fa "uint32_t tpl_id" +.Fa "uint32_t flags" +.Fc +.Ft int +.Fo stats_blob_clone +.Fa "struct statsblob **dst" +.Fa "size_t dstmaxsz" +.Fa "struct statsblob *src" +.Fa "uint32_t flags" +.Fc +.Ft void +.Fo stats_blob_destroy +.Fa "struct statsblob *sb" +.Fc +.Ft int +.Fo stats_voistat_fetch_dptr +.Fa "struct statsblob *sb" +.Fa "int32_t voi_id" +.Fa "enum voi_stype stype" +.Fa "enum vsd_dtype *retdtype" +.Fa "struct voistatdata **retvsd" +.Fa "size_t *retvsdsz" +.Fc +.Ft int +.Fo stats_voistat_fetch_<dtype> +.Fa "struct statsblob *sb" +.Fa "int32_t voi_id" +.Fa "enum voi_stype stype" +.Fa "<dtype> *ret" +.Fc +.Ft int +.Fo stats_blob_snapshot +.Fa "struct statsblob **dst" +.Fa "size_t dstmaxsz" +.Fa "struct statsblob *src" +.Fa "uint32_t flags" +.Fc +.Ft int +.Fo stats_blob_tostr +.Fa "struct statsblob *sb" +.Fa "struct sbuf *buf" +.Fa "enum sb_str_fmt fmt" +.Fa "uint32_t flags" +.Fc +.Ft int +.Fo stats_voistatdata_tostr +.Fa "const struct voistatdata *vsd" +.Fa "enum vsd_dtype dtype" +.Fa "enum sb_str_fmt fmt" +.Fa "struct sbuf *buf" +.Fa "int objdump" +.Fc +.Ft typedef int +.Fn "\*(lp*stats_blob_visitcb_t\*(rp" "struct sb_visit *sbv" "void *usrctx" +.Ft int +.Fo stats_blob_visit +.Fa "struct statsblob *sb" +.Fa "stats_blob_visitcb_t func" +.Fa "void *usrctx" +.Fc +.Sh DESCRIPTION +The +.Nm +framework facilitates real-time kernel and user space statistics gathering. +The framework is built around the +.Dq statsblob , +an object embedded within a contiguous memory allocation that is mostly opaque +to consumers and stores all required state. +A +.Dq statsblob +object can itself be embedded within other objects either directly or indirectly +using a pointer. +.Pp +Objects or subsystems for which statistics are to be gathered are initialized +from a template +.Dq statsblob , +which acts as the blueprint for an arbitrary set of +Variables Of Interest (VOIs) and their associated statistics. +Each template defines a schema plus associated metadata, which are kept separate +to minimize the memory footprint of blobs. +.Pp +Data gathering hook functions added at appropriate locations within the code +base of interest feed VOI data into the framework for processing. +.Pp +Each +.Dq statsblob , +consists of a +.Vt struct statsblob +header and opaque internal blob structure per the following diagram: +.Bd -literal -offset indent +--------------------------------------------------------- +| struct | uint8_t | +| statsblob | opaque[] | +--------------------------------------------------------- +.Ed +.Pp +The publicly visible 8-byte header is defined as: +.Bd -literal -offset indent +struct statsblob { + uint8_t abi; + uint8_t endian; + uint16_t flags; + uint16_t maxsz; + uint16_t cursz; + uint8_t opaque[]; +}; +.Ed +.Pp +.Va abi +specifies which API version the blob's +.Va opaque +internals conform to +.Pq Dv STATS_ABI_V1 is the only version currently defined . +.Va endian +specifies the endianness of the blob's fields +.Po +.Dv SB_LE +for little endian, +.Dv SB_BE +for big endian, or +.Dv SB_UE +for unknown endianness +.Pc . +.Va cursz +specifies the size of the blob, while +.Va maxsz +specifies the size of the underlying memory allocation in which the +blob is embedded. +Both +.Va cursz +and +.Va maxsz +default to units of bytes, unless a flag is set in +.Va flags +that dictates otherwise. +.Pp +Templates are constructed by associating arbitrary VOI IDs with a set of +statistics, where each statistic is specified using a +.Vt struct voistatspec +per the definition below: +.Bd -literal -offset indent +struct voistatspec { + vss_hlpr_fn hlpr; + struct vss_hlpr_info *hlprinfo; + struct voistatdata *iv; + size_t vsdsz; + uint32_t flags; + enum vsd_dtype vs_dtype : 8; + enum voi_stype stype : 8; +}; +.Ed +.Pp +It is generally expected that consumers will not work with +.Vt struct voistatspec +directly, and instead use the +.Fn STATS_VSS_* +helper macros. +.Pp +The +.Nm +framework offers the following statistics for association with VOIs: +.Bl -tag -width ".Dv VS_STYPE_TDGST" +.It Dv VS_STYPE_SUM +The sum of VOI values. +.It Dv VS_STYPE_MAX +The maximum VOI value. +.It Dv VS_STYPE_MIN +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 +values which did not match any bucket. +Histograms can be specified as +.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 +.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 +.Po refer to the t-digest paper in the +.Sx SEE ALSO +section below +.Pc . +.El +.Pp +A +.Dq visitor software design pattern Ns +-like scheme is employed to facilitate iterating over a blob's data without +concern for the blob's structure. +The data provided to visitor callback functions is encapsulated in +.Vt struct sb_visit +per the definition below: +.Bd -literal -offset indent +struct sb_visit { + struct voistatdata *vs_data; + uint32_t tplhash; + uint32_t flags; + int16_t voi_id; + int16_t vs_dsz; + enum vsd_dtype voi_dtype : 8; + enum vsd_dtype vs_dtype : 8; + int8_t vs_stype; + uint16_t vs_errs; +}; +.Ed +.Pp +The +.Fn stats_tpl_sample_rates +and +.Fn stats_tpl_sample_rollthedice +functions utilize +.Vt struct stats_tpl_sample_rate +to encapsulate per-template sample rate information per the definition below: +.Bd -literal -offset indent +struct stats_tpl_sample_rate { + int32_t tpl_slot_id; + uint32_t tpl_sample_pct; +}; +.Ed +.Pp +The +.Va tpl_slot_id +member holds the template's slot ID obtained from +.Fn stats_tpl_alloc +or +.Fn stats_tpl_fetch_allocid . +The +.Va tpl_sample_pct +member holds the template's sample rate as an integer percentage in the range +[0,100]. +.Pp +The +.Vt stats_tpl_sr_cb_t +conformant function pointer that is required as the +.Fa arg1 +of +.Fn stats_tpl_sample_rates +is defined as: +.Bd -literal -offset indent +enum stats_tpl_sr_cb_action { + TPL_SR_UNLOCKED_GET, + TPL_SR_RLOCKED_GET, + TPL_SR_RUNLOCK, + TPL_SR_PUT +}; +typedef int (*stats_tpl_sr_cb_t)(enum stats_tpl_sr_cb_action action, + struct stats_tpl_sample_rate **rates, int *nrates, void *ctx); +.Ed +.Pp +It is required that a conformant function: +.Bl -dash +.It +Return an appropriate +.Xr errno 2 +on error, otherwise 0. +.It +When called with +.Qq action == TPL_SR_*_GET , +return the subsystem's rates list ptr and count, locked or unlocked as +requested. +.It +When called with +.Qq action == TPL_SR_RUNLOCK , +unlock the subsystem's rates list ptr and count. +Pair with a prior +.Qq action == TPL_SR_RLOCKED_GET +call. +.It +When called with +.Qq action == TPL_SR_PUT , +update the subsystem's rates list ptr and count to the sysctl processed values +and return the inactive list details in +.Fa rates +and +.Fa nrates +for garbage collection by +.Fn stats_tpl_sample_rates . +.El +.Pp +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> Ns +:<tplhash> +.Ns , for example +.Qq TCP_DEFAULT Ns +:1731235399 +.It +.Qq <tplname> +.Ns , for example +.Qq TCP_DEFAULT +.It +:<tplhash> +.Ns , for example +:1731235399 +.El +.Pp +The first form is the normative spec format generated by the framework, while +the second and third forms are convenience formats primarily for user input. +The use of inverted commas around the template name is optional. +.Ss MIB Variables +The in-kernel +.Nm +framework exposes the following framework-specific variables in the +.Va kern.stats +branch of the +.Xr sysctl 3 +MIB. +.Bl -tag -width "templates" +.It templates +Read-only CSV list of registered templates in normative template spec form. +.El +.Ss Template Management Functions +The +.Fn stats_tpl_alloc +function allocates a new template with the specified unique name and returns its +runtime-stable template slot ID for use with other API functions. +The +.Fa flags +argument is currently unused. +.Pp +The +.Fn stats_tpl_fetch_allocid +function returns the runtime-stable template slot ID of any registered template +matching the specified name and hash. +.Pp +The +.Fn stats_tpl_fetch +function returns the pointer to the registered template object at the specified +template slot ID. +.Pp +The +.Fn stats_tpl_id2name +function returns the name of the registered template object at the specified +template slot ID. +.Pp +The +.Fn stats_tpl_sample_rates +function provides a generic handler for template sample rates management and +reporting via +.Xr sysctl 3 +MIB variables. +Subsystems can use this function to create a subsystem-specific +.Xr SYSCTL_PROC 9 +MIB variable that manages and reports subsystem-specific template sampling +rates. +Subsystems must supply a +.Vt stats_tpl_sr_cb_t +conformant function pointer as the sysctl's +.Fa arg1 , +which is a callback used to interact with the subsystem's stats template sample +rates list. +Subsystems can optionally specify the sysctl's +.Fa arg2 +as non-zero, which causes a zero-initialized allocation of arg2-sized contextual +memory to be heap-allocated and passed in to all subsystem callbacks made during +the operation of +.Fn stats_tpl_sample_rates . +.Pp +The +.Fn stats_tpl_sample_rollthedice +function makes a weighted random template selection from the supplied array of +template sampling rates. +The cumulative percentage of all sampling rates should not exceed 100. +If no seed is supplied, a PRNG is used to generate a true random number so that +every selection is independent. +If a seed is supplied, selection will be made randomly across different seeds, but +deterministically given the same seed. +.Pp +The +.Fn stats_tpl_add_voistats +function is used to add a VOI and associated set of statistics to the registered +template object at the specified template slot ID. +The set of statistics is passed as an array of +.Vt struct voistatspec +which can be initialized using the +.Fn STATS_VSS_* +helper macros or manually for non-standard use cases. +For static +.Fa vss +arrays, the +.Fa nvss +count of array elements can be determined by passing +.Fa vss +to the +.Fn NVSS +macro. +The +.Dv SB_VOI_RELUPDATE +flag can be passed to configure the VOI for use with +.Fn stats_voi_update_rel_<dtype> , +which entails maintaining an extra 8 bytes of state in the blob at each update. +.Ss Data Gathering Functions +The +.Fn stats_voi_update_abs_<dtype> +and +.Fn stats_voi_update_rel_<dtype> +functions both update all the statistics associated with the VOI identified by +.Fa voi_id . +The +.Dq abs +call uses +.Fa voival +as an absolute value, whereas the +.Dq rel +call uses +.Fa voival +as a value relative to that of the previous update function call, by adding it +to the previous value and using the result for the update. +Relative updates are only possible for VOIs that were added to the template with +the +.Dv SB_VOI_RELUPDATE +flag specified to +.Fn stats_tpl_add_voistats . +.Ss Utility Functions +The +.Fn stats_blob_alloc +function allocates and initializes a new blob based on the registered template +object at the specified template slot ID. +.Pp +The +.Fn stats_blob_init +function initializes a new blob in an existing memory allocation based on the +registered template object at the specified template slot ID. +.Pp +The +.Fn stats_blob_clone +function duplicates the +.Fa src +blob into +.Fa dst , +leaving only the +.Va maxsz +field of +.Fa dst +untouched. +The +.Dv SB_CLONE_ALLOCDST +flag can be passed to instruct the function to allocate a new blob of +appropriate size into which to clone +.Fa src , +storing the new pointer in +.Fa *dst . +The +.Dv SB_CLONE_USRDSTNOFAULT +or +.Dv SB_CLONE_USRDST +flags can be set to respectively signal that +.Xr copyout_nofault 9 +or +.Xr copyout 9 +should be used because +.Fa *dst +is a user space address. +.Pp +The +.Fn stats_blob_snapshot +function calls +.Fn stats_blob_clone +to obtain a copy of +.Fa src +and then performs any additional functions required to produce a coherent +blob snapshot. +The flags interpreted by +.Fn stats_blob_clone +also apply to +.Fn stats_blob_snapshot . +Additionally, the +.Dv SB_CLONE_RSTSRC +flag can be used to effect a reset of the +.Fa src +blob's statistics after a snapshot is successfully taken. +.Pp +The +.Fn stats_blob_destroy +function destroys a blob previously created with +.Fn stats_blob_alloc , +.Fn stats_blob_clone +or +.Fn stats_blob_snapshot . +.Pp +The +.Fn stats_blob_visit +function allows the caller to iterate over the contents of a blob. +The callback function +.Fa func +is called for every VOI and statistic in the blob, passing a +.Vt struct sb_visit +and the user context argument +.Fa usrctx +to the callback function. +The +.Fa sbv +passed to the callback function may have one or more of the following flags set +in the +.Va flags +struct member to provide useful metadata about the iteration: +.Dv SB_IT_FIRST_CB , +.Dv SB_IT_LAST_CB , +.Dv SB_IT_FIRST_VOI , +.Dv SB_IT_LAST_VOI , +.Dv SB_IT_FIRST_VOISTAT , +.Dv SB_IT_LAST_VOISTAT , +.Dv SB_IT_NULLVOI +and +.Dv SB_IT_NULLVOISTAT . +Returning a non-zero value from the callback function terminates the iteration. +.Pp +The +.Fn stats_blob_tostr +renders a string representation of a blob into the +.Xr sbuf 9 +.Fa buf . +Currently supported render formats are +.Dv SB_STRFMT_FREEFORM +and +.Dv SB_STRFMT_JSON . +The +.Dv SB_TOSTR_OBJDUMP +flag can be passed to render version specific opaque implementation detail for +debugging or string-to-binary blob reconstruction purposes. +The +.Dv SB_TOSTR_META +flag can be passed to render template metadata into the string representation, +using the blob's template hash to lookup the corresponding template. +.Pp +The +.Fn stats_voistatdata_tostr +renders a string representation of an individual statistic's data into the +.Xr sbuf 9 +.Fa buf . +The same render formats supported by the +.Fn stats_blob_tostr +function can be specified, and the +.Fa objdump +boolean has the same meaning as the +.Dv SB_TOSTR_OBJDUMP +flag. +.Pp +The +.Fn stats_voistat_fetch_dptr +function returns an internal blob pointer to the specified +.Fa stype +statistic data for the VOI +.Fa voi_id . +The +.Fn stats_voistat_fetch_<dtype> +functions are convenience wrappers around +.Fn stats_voistat_fetch_dptr +to perform the extraction for simple data types. +.Sh IMPLEMENTATION NOTES +The following notes apply to STATS_ABI_V1 format statsblobs. +.Ss Space-Time Complexity +Blobs are laid out as three distinct memory regions following the header: +.Bd -literal -offset indent +------------------------------------------------------ +| struct | struct | struct | struct | +| statsblobv1 | voi [] | voistat [] | voistatdata [] | +------------------------------------------------------ +.Ed +.Pp +Blobs store VOI and statistic blob state +.Po +8 bytes for +.Vt struct voi +and 8 bytes for +.Vt struct voistat +respectively +.Pc +in sparse arrays, using the +.Fa voi_id +and +.Vt enum voi_stype +as array indices. +This allows O(1) access to any voi/voistat pair in the blob, at the expense of +8 bytes of wasted memory per vacant slot for templates which do not specify +contiguously numbered VOIs and/or statistic types. +Data storage for statistics is only allocated for non-vacant slot pairs. +.Pp +To provide a concrete example, a blob with the following specification: +.Bl -dash +.It +Two VOIs; ID 0 and 2; added to the template in that order +.It +VOI 0 is of data type +.Vt int64_t , +is configured with +.Dv SB_VOI_RELUPDATE +to enable support for relative updates using +.Fn stats_voi_update_rel_<dtype> , +and has a +.Dv VS_STYPE_MIN +statistic associated with it. +.It +VOI 2 is of data type +.Vt uint32_t +with +.Dv VS_STYPE_SUM +and +.Dv VS_STYPE_MAX +statistics associated with it. +.El +.Pp +would have the following memory layout: +.Bd -literal +-------------------------------------- +| header | struct statsblobv1, 32 bytes +|------------------------------------| +| voi[0] | struct voi, 8 bytes +| voi[1] (vacant) | struct voi, 8 bytes +| voi[2] | struct voi, 8 bytes +|------------------------------------| +| voi[2]voistat[VOISTATE] (vacant) | struct voistat, 8 bytes +| voi[2]voistat[SUM] | struct voistat, 8 bytes +| voi[2]voistat[MAX] | struct voistat, 8 bytes +| voi[0]voistat[VOISTATE] | struct voistat, 8 bytes +| voi[0]voistat[SUM] (vacant) | struct voistat, 8 bytes +| voi[0]voistat[MAX] (vacant) | struct voistat, 8 bytes +| voi[0]voistat[MIN] | struct voistat, 8 bytes +|------------------------------------| +| voi[2]voistat[SUM]voistatdata | struct voistatdata_int32, 4 bytes +| voi[2]voistat[MAX]voistatdata | struct voistatdata_int32, 4 bytes +| voi[0]voistat[VOISTATE]voistatdata | struct voistatdata_numeric, 8 bytes +| voi[0]voistat[MIN]voistatdata | struct voistatdata_int64, 8 bytes +-------------------------------------- + TOTAL 136 bytes +.Ed +.Pp +When rendered to string format using +.Fn stats_blob_tostr , +the +.Dv SB_STRFMT_FREEFORM +.Fa fmt +and the +.Dv SB_TOSTR_OBJDUMP +flag, the rendered output is: +.Bd -literal +struct statsblobv1@0x8016250a0, abi=1, endian=1, maxsz=136, cursz=136, \\ + created=6294158585626144, lastrst=6294158585626144, flags=0x0000, \\ + stats_off=56, statsdata_off=112, tplhash=2994056564 + vois[0]: id=0, name="", flags=0x0001, dtype=INT_S64, voistatmaxid=3, \\ + stats_off=80 + vois[0]stat[0]: stype=VOISTATE, flags=0x0000, dtype=VOISTATE, \\ + dsz=8, data_off=120 + voistatdata: prev=0 + vois[0]stat[1]: stype=-1 + vois[0]stat[2]: stype=-1 + vois[0]stat[3]: stype=MIN, flags=0x0000, dtype=INT_S64, \\ + dsz=8, data_off=128 + voistatdata: 9223372036854775807 + vois[1]: id=-1 + vois[2]: id=2, name="", flags=0x0000, dtype=INT_U32, voistatmaxid=2, \\ + stats_off=56 + vois[2]stat[0]: stype=-1 + vois[2]stat[1]: stype=SUM, flags=0x0000, dtype=INT_U32, dsz=4, \\ + data_off=112 + voistatdata: 0 + vois[2]stat[2]: stype=MAX, flags=0x0000, dtype=INT_U32, dsz=4, \\ + data_off=116 + voistatdata: 0 +.Ed +.Pp +Note: The +.Qq \e +present in the rendered output above indicates a manual line break inserted to +keep the man page within 80 columns and is not part of the actual output. +.Ss Locking +The +.Nm +framework does not provide any concurrency protection at the individual blob +level, instead requiring that consumers guarantee mutual exclusion when calling +API functions that reference a non-template blob. +.Pp +The list of templates is protected with a +.Xr rwlock 9 +in-kernel, and +.Xr pthread 3 +rw lock in user space to support concurrency between template management and +blob initialization operations. +.Sh RETURN VALUES +.Fn stats_tpl_alloc +returns a runtime-stable template slot ID on success, or a negative errno on +failure. +-EINVAL is returned if any problems are detected with the arguments. +-EEXIST is returned if an existing template is registered with the same name. +-ENOMEM is returned if a required memory allocation fails. +.Pp +.Fn stats_tpl_fetch_allocid +returns a runtime-stable template slot ID, or negative errno on failure. +-ESRCH is returned if no registered template matches the specified name and/or +hash. +.Pp +.Fn stats_tpl_fetch +returns 0 on success, or ENOENT if an invalid +.Fa tpl_id +is specified. +.Pp +.Fn stats_tpl_id2name +returns 0 on success, or an errno on failure. +EOVERFLOW is returned if the length of +.Fa buf +specified by +.Fa len +is too short to hold the template's name. +ENOENT is returned if an invalid +.Fa tpl_id +is specified. +.Pp +.Fn stats_tpl_sample_rollthedice +returns a valid template slot id selected from +.Fa rates +or -1 if a NULL selection was made, that is no stats collection this roll. +.Pp +.Fn stats_tpl_add_voistats +return 0 on success, or an errno on failure. +EINVAL is returned if any problems are detected with the arguments. +EFBIG is returned if the resulting blob would have exceeded the maximum size. +EOPNOTSUPP is returned if an attempt is made to add more VOI stats to a +previously configured VOI. +ENOMEM is returned if a required memory allocation fails. +.Pp +.Fn stats_voi_update_abs_<dtype> +and +.Fn stats_voi_update_rel_<dtype> +return 0 on success, or EINVAL if any problems are detected with the arguments. +.Pp +.Fn stats_blob_init +returns 0 on success, or an errno on failure. +EINVAL is returned if any problems are detected with the arguments. +EOVERFLOW is returned if the template blob's +.Fa cursz +is larger than the +.Fa maxsz +of the blob being initialized. +.Pp +.Fn stats_blob_alloc +returns a pointer to a newly allocated and initialized blob based on the +specified template with slot ID +.Fa tpl_id , +or NULL if the memory allocation failed. +.Pp +.Fn stats_blob_clone +and +.Fn stats_blob_snapshot +return 0 on success, or an errno on failure. +EINVAL is returned if any problems are detected with the arguments. +ENOMEM is returned if the SB_CLONE_ALLOCDST flag was specified and the memory +allocation for +.Fa dst +fails. +EOVERFLOW is returned if the src blob's +.Fa cursz +is larger than the +.Fa maxsz +of the +.Fa dst +blob. +.Pp +.Fn stats_blob_visit +returns 0 on success, or EINVAL if any problems are detected with the arguments. +.Pp +.Fn stats_blob_tostr +and +.Fn stats_voistatdata_tostr +return 0 on success, or an errno on failure. +EINVAL is returned if any problems are detected with the arguments, otherwise +any error returned by +.Fn sbuf_error +for +.Fa buf +is returned. +.Pp +.Fn stats_voistat_fetch_dptr +returns 0 on success, or EINVAL if any problems are detected with the arguments. +.Pp +.Fn stats_voistat_fetch_<dtype> +returns 0 on success, or an errno on failure. +EINVAL is returned if any problems are detected with the arguments. +EFTYPE is returned if the requested data type does not match the blob's data +type for the specified +.Fa voi_id +and +.Fa stype . +.Sh SEE ALSO +.Xr errno 2 , +.Xr arb 3 , +.Xr qmath 3 , +.Xr tcp 4 , +.Xr sbuf 9 +.Rs +.%A "Ted Dunning" +.%A "Otmar Ertl" +.%T "Computing Extremely Accurate Quantiles Using t-digests" +.%U "https://github.com/tdunning/t-digest/raw/master/docs/t-digest-paper/histo.pdf" +.Re +.Sh HISTORY +The +.Nm +framework first appeared in +.Fx 13.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +framework and this manual page were written by +.An Lawrence Stewart Aq lstewart@FreeBSD.org +and sponsored by Netflix, Inc. +.Sh CAVEATS +Granularity of timing-dependent network statistics, in particular TCP_RTT, +depends on the +.Dv HZ +timer. +To minimize the measurement error avoid using HZ lower than 1000. diff --git a/static/freebsd/man3/stdarg.3 b/static/freebsd/man3/stdarg.3 new file mode 100644 index 00000000..71409508 --- /dev/null +++ b/static/freebsd/man3/stdarg.3 @@ -0,0 +1,243 @@ +.\" Copyright (c) 1990, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" 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 October 18, 2024 +.Dt STDARG 3 +.Os +.Sh NAME +.Nm stdarg +.Nd variable argument lists +.Sh SYNOPSIS +.In stdarg.h +.Ft void +.Fn va_start "va_list ap" last +.Ft type +.Fn va_arg "va_list ap" type +.Ft void +.Fn va_copy "va_list dest" "va_list src" +.Ft void +.Fn va_end "va_list ap" +.Sh DESCRIPTION +A function may be called with a varying number of arguments of varying +types. +The include file +.In stdarg.h +declares a type +.Pq Em va_list +and defines four macros for stepping +through a list of arguments whose number and types are not known to +the called function. +.Pp +The called function must declare an object of type +.Em va_list +which is used by the macros +.Fn va_start , +.Fn va_arg , +.Fn va_copy , +and +.Fn va_end . +.Pp +The +.Fn va_start +macro initializes +.Fa ap +for subsequent use by +.Fn va_arg , +.Fn va_copy , +and +.Fn va_end , +and must be called first. +.Pp +The parameter +.Fa last +is the name of the last parameter before the variable argument list, +i.e., the last parameter of which the calling function knows the type. +.Pp +Because the address of this parameter is used in the +.Fn va_start +macro, it should not be declared as a register variable, or as a +function or an array type. +.Pp +The +.Fn va_arg +macro expands to an expression that has the type and value of the next +argument in the call. +The parameter +.Fa ap +is the +.Em va_list Fa ap +initialized by +.Fn va_start +or +.Fn va_copy . +Each call to +.Fn va_arg +modifies +.Fa ap +so that the next call returns the next argument. +The parameter +.Fa type +is a type name specified so that the type of a pointer to an +object that has the specified type can be obtained simply by +adding a * +to +.Fa type . +.Pp +If there is no next argument, or if +.Fa type +is not compatible with the type of the actual next argument +(as promoted according to the default argument promotions), +random errors will occur. +.Pp +The first use of the +.Fn va_arg +macro after that of the +.Fn va_start +macro returns the argument after +.Fa last . +Successive invocations return the values of the remaining +arguments. +.Pp +The +.Fn va_copy +macro copies a variable argument list, previously initialized by +.Fn va_start , +from +.Fa src +to +.Fa dest . +The state is preserved such that it is equivalent to calling +.Fn va_start +with the same second argument used with +.Fa src , +and calling +.Fn va_arg +the same number of times as called with +.Fa src . +.Pp +The +.Fn va_end +macro cleans up any state associated with the variable argument list +.Fa ap . +.Pp +Each invocation of +.Fn va_start +or +.Fn va_copy +must be paired with a corresponding invocation of +.Fn va_end +in the same function. +.Sh RETURN VALUES +The +.Fn va_arg +macro returns the value of the next argument. +.Pp +The +.Fn va_start , +.Fn va_copy , +and +.Fn va_end +macros return no value. +.Sh EXAMPLES +The function +.Em foo +takes a string of format characters and prints out the argument +associated with each format character based on the type. +.Bd -literal -offset indent +void foo(char *fmt, ...) +{ + va_list ap; + int d; + char c, *s; + + va_start(ap, fmt); + while (*fmt) + switch(*fmt++) { + case 's': /* string */ + s = va_arg(ap, char *); + printf("string %s\en", s); + break; + case 'd': /* int */ + d = va_arg(ap, int); + printf("int %d\en", d); + break; + case 'c': /* char */ + /* Note: char is promoted to int. */ + c = va_arg(ap, int); + printf("char %c\en", c); + break; + } + va_end(ap); +} +.Ed +.Sh COMPATIBILITY +These macros are +.Em not +compatible with the historic macros they replace. +.Sh STANDARDS +The +.Fn va_start , +.Fn va_arg , +.Fn va_copy , +and +.Fn va_end +macros conform to +.St -isoC-99 . +.Sh HISTORY +The +.Fn va_start , +.Fn va_arg +and +.Fn va_end +macros were introduced in +.St -ansiC . +The +.Fn va_copy +macro was introduced in +.St -isoC-99 . +.Sh BUGS +Unlike the +.Em varargs +macros, the +.Nm +macros do not permit programmers to +code a function with no fixed arguments. +This problem generates work mainly when converting +.Em varargs +code to +.Nm +code, +but it also creates difficulties for variadic functions that +wish to pass all of their arguments on to a function +that takes a +.Em va_list +argument, such as +.Xr vfprintf 3 . diff --git a/static/freebsd/man3/stdbit.3 b/static/freebsd/man3/stdbit.3 new file mode 100644 index 00000000..bdee56cc --- /dev/null +++ b/static/freebsd/man3/stdbit.3 @@ -0,0 +1,120 @@ +.\" +.\" Copyright (c) 2025 Robert Clausecker <fuz@FreeBSD.org> +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.Dd November 9, 2025 +.Dt STDBIT 3 +.Os +.Sh NAME +.Nm stdbit +.Nd bit and byte utilities +.Sh SYNOPSIS +.Lb libc +.In stdbit.h +.Fd #define __STDC_ENDIAN_LITTLE__ +.Fd #define __STDC_ENDIAN_BIG__ +.Fd #define __STDC_ENDIAN_NATIVE__ +.Ft unsigned int +.Fn stdc_count_leading_zeros "value" +.Ft unsigned int +.Fn stdc_count_leading_ones "value" +.Ft unsigned int +.Fn stdc_count_trailing_zeros "value" +.Ft unsigned int +.Fn stdc_count_trailing_ones "value" +.Ft unsigned int +.Fn stdc_first_leading_zero "value" +.Ft unsigned int +.Fn stdc_first_leading_one "value" +.Ft unsigned int +.Fn stdc_first_trailing_zero "value" +.Ft unsigned int +.Fn stdc_first_trailing_one "value" +.Ft unsigned int +.Fn stdc_count_zeros "value" +.Ft unsigned int +.Fn stdc_count_ones "value" +.Ft bool +.Fn stdc_has_single_bit "value" +.Ft unsigned int +.Fn stdc_bit_width "value" +.Ft typeof Ns Pq Em value +.Fn stdc_bit_floor "value" +.Ft typeof Ns Pq Em value +.Fn stdc_bit_ceil "value" +.Sh DESCRIPTION +The +.Dv __STDC_ENDIAN_NATIVE__ +macro describes the byte order or endianness of the machine for which the +program is built. +If the machine has big-endian byte order, this macro is equal to +.Dv __STDC_ENDIAN_BIG__ . +If the machine has little-endian byte order, this macro is equal to +.Dv __STDC_ENDIAN_LITTLE__ . +Otherwise, the macro has a value that is equal to neither. +.Pp +The bit and byte utility functions analyze the bits within a datum. +Each function +.Em func +is provided in five variants +.Nm stdc_ Ns Em func Ns Em _ Ns Em type Ns Pq Em value +where +.Fa value +is of type +.Va unsigned char , +.Va unsigned short , +.Va unsigned int , +.Va unsigned long , +or +.Va unsigned long long +for +.Em type +being +.Sy uc , +.Sy us , +.Sy ui , +.Sy ul , +or +.Sy ull +respectively. +Additionally, for each +.Em func , +a type-generic macro +.Nm stdc_ Ns Em func Ns Pq Em value +that picks the appropriate function +.Nm stdc_ Ns Em func Ns Em _ Ns Em type Ns Pq Em value +based on the type of +.Fa value +is provided. +.Sh SEE ALSO +.Xr arch 7 , +.Xr bitstring 3 , +.Xr ffs 3 , +.Xr fls 3 , +.Xr stdc_count_leading_zeros 3 , +.Xr stdc_count_leading_ones 3 , +.Xr stdc_count_trailing_zeros 3 , +.Xr stdc_count_trailing_ones 3 , +.Xr stdc_first_leading_zero 3 , +.Xr stdc_first_leading_one 3 , +.Xr stdc_first_trailing_zero 3 , +.Xr stdc_first_trailing_one 3 , +.Xr stdc_count_zeros 3 , +.Xr stdc_count_ones 3 , +.Xr stdc_has_single_bit 3 , +.Xr stdc_bit_width 3 , +.Xr stdc_bit_floor 3 , +.Xr stdc_bit_ceil 3 +.Sh STANDARDS +The macros and functions of the +.In stdbit.h +header conform to +.St -isoC-2023 . +.Sh HISTORY +The +.In stdbit.h +header and the macros and functions defined therein where added in +.Fx 15.1. +.Sh AUTHOR +.An Robert Clausecker Aq Mt fuz@FreeBSD.org diff --git a/static/freebsd/man3/stdckdint.3 b/static/freebsd/man3/stdckdint.3 new file mode 100644 index 00000000..4f12b4a8 --- /dev/null +++ b/static/freebsd/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-2023 . +.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/static/freebsd/man3/sysexits.3 b/static/freebsd/man3/sysexits.3 new file mode 100644 index 00000000..62f79b28 --- /dev/null +++ b/static/freebsd/man3/sysexits.3 @@ -0,0 +1,135 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" 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 +.\" 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 DEVELOPERS ``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 DEVELOPERS 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 May 9, 2024 +.Dt SYSEXITS 3 +.Os +.Sh NAME +.Nm sysexits +.Nd legacy exit status codes for system programs +.Sh SYNOPSIS +.In sysexits.h +.Sh DESCRIPTION +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 +.Sy EX__BASE +to reduce the possibility of clashing with other exit statuses that +random programs may already return. +The meaning of the codes is +approximately as follows: +.Bl -tag -width "EX_UNAVAILABLEXX(XX)" +.It Sy EX_USAGE Pq 64 +The command was used incorrectly, e.g., with the wrong number of +arguments, a bad flag, a bad syntax in a parameter, or whatever. +.It Sy EX_DATAERR Pq 65 +The input data was incorrect in some way. +This should only be used +for user's data and not system files. +.It Sy EX_NOINPUT Pq 66 +An input file (not a system file) did not exist or was not readable. +This could also include errors like +.Dq \&No message +to a mailer (if it cared to catch it). +.It Sy EX_NOUSER Pq 67 +The user specified did not exist. +This might be used for mail +addresses or remote logins. +.It Sy EX_NOHOST Pq 68 +The host specified did not exist. +This is used in mail addresses or +network requests. +.It Sy EX_UNAVAILABLE Pq 69 +A service is unavailable. +This can occur if a support program or file +does not exist. +This can also be used as a catchall message when +something you wanted to do does not work, but you do not know why. +.It Sy EX_SOFTWARE Pq 70 +An internal software error has been detected. +This should be limited +to non-operating system related errors as possible. +.It Sy EX_OSERR Pq 71 +An operating system error has been detected. +This is intended to be +used for such things as +.Dq cannot fork , +.Dq cannot create pipe , +or the like. +It includes things like getuid returning a user that +does not exist in the passwd file. +.It Sy EX_OSFILE Pq 72 +Some system file (e.g., +.Pa /etc/passwd , +.Pa /var/run/utx.active , +etc.) does not exist, cannot be opened, or has some sort of error +(e.g., syntax error). +.It Sy EX_CANTCREAT Pq 73 +A (user specified) output file cannot be created. +.It Sy EX_IOERR Pq 74 +An error occurred while doing I/O on some file. +.It Sy EX_TEMPFAIL Pq 75 +Temporary failure, indicating something that is not really an error. +In sendmail, this means that a mailer (e.g.) could not create a +connection, and the request should be reattempted later. +.It Sy EX_PROTOCOL Pq 76 +The remote system returned something that was +.Dq not possible +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 +.Sy EX_NOINPUT +or +.Sy EX_CANTCREAT , +but rather for higher level permissions. +.It Sy EX_CONFIG Pq 78 +Something was found in an unconfigured or misconfigured state. +.El +.Pp +The numerical values corresponding to the symbolical ones are given in +parenthesis for easy reference. +.Sh SEE ALSO +.Xr err 3 , +.Xr exit 3 , +.Xr style 9 +.Sh HISTORY +The +.Nm +file first appeared in +.Bx 4 . +.Sh AUTHORS +This manual page was written by +.An J\(:org Wunsch . +.Sh BUGS +.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/static/freebsd/man3/tgmath.3 b/static/freebsd/man3/tgmath.3 new file mode 100644 index 00000000..98dbb743 --- /dev/null +++ b/static/freebsd/man3/tgmath.3 @@ -0,0 +1,160 @@ +.\" Copyright (c) 2004 Stefan Farfeleder +.\" 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 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 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 January 4, 2012 +.Dt TGMATH 3 +.Os +.Sh NAME +.Nm tgmath +.Nd "type-generic macros" +.Sh SYNOPSIS +.In tgmath.h +.Sh DESCRIPTION +The header +.In tgmath.h +provides type-generic macros +for +.In math.h +and +.In complex.h +functions that have +.Vt float +(suffixed with +.Sy f ) , +.Vt double +and +.Vt "long double" +(suffixed with +.Sy l ) +versions. +The arguments that vary across the three functions and have type +.Vt float , double +and +.Vt "long double" , +respectively, are called +.Em "generic arguments" . +.Pp +The following rules describe which function is actually called if a +type-generic macro is invoked. +If any generic argument has type +.Vt "long double" +or +.Vt "long double complex" , +the +.Vt "long double" +function is called. +Else, if any generic argument has type +.Vt double , "double complex" +or an integer type, the +.Vt double +version is invoked. +Otherwise, the macro expands to the +.Vt float +implementation. +.Pp +For the macros in the following table, both real and complex functions +exist. +The real functions are prototyped in +.In math.h +and the complex equivalents in +.In complex.h . +The complex function is called if any of the generic arguments is a +complex value. +Otherwise, the real equivalent is called. +.Bl -column -offset indent ".Fn acosh" "Sy real function" ".Sy complex function" +.It Sy Macro Ta Sy real function Ta Sy complex function +.It Fn acos Ta Fn acos Ta Fn cacos +.It Fn asin Ta Fn asin Ta Fn casin +.It Fn atan Ta Fn atan Ta Fn catan +.It Fn acosh Ta Fn acosh Ta Fn cacosh +.It Fn asinh Ta Fn asinh Ta Fn casinh +.It Fn atanh Ta Fn atanh Ta Fn catanh +.It Fn cos Ta Fn cos Ta Fn ccos +.It Fn sin Ta Fn sin Ta Fn csin +.It Fn tan Ta Fn tan Ta Fn ctan +.It Fn cosh Ta Fn cosh Ta Fn ccosh +.It Fn sinh Ta Fn sinh Ta Fn csinh +.It Fn tanh Ta Fn tanh Ta Fn ctanh +.It Fn exp Ta Fn exp Ta Fn cexp +.It Fn log Ta Fn log Ta Fn clog +.It Fn pow Ta Fn pow Ta Fn cpow +.It Fn sqrt Ta Fn sqrt Ta Fn csqrt +.It Fn fabs Ta Fn fabs Ta Fn cabs +.El +.Pp +No complex functions exist for the following macros, so passing a +complex value to a generic argument invokes undefined behaviour: +.Bl -column -offset indent ".Fn nexttoward" ".Fn nexttoward" ".Fn nexttoward" ".Fn nexttoward" +.It Fn atan2 Ta Fn fma Ta Fn llround Ta Fn remainder +.It Fn cbrt Ta Fn fmax Ta Fn log10 Ta Fn remquo +.It Fn ceil Ta Fn fmin Ta Fn log1p Ta Fn rint +.It Fn copysign Ta Fn fmod Ta Fn log2 Ta Fn round +.It Fn erf Ta Fn frexp Ta Fn logb Ta Fn scalbn +.It Fn erfc Ta Fn hypot Ta Fn lrint Ta Fn scalbln +.It Fn exp2 Ta Fn ilogb Ta Fn lround Ta Fn tgamma +.It Fn expm1 Ta Fn ldexp Ta Fn nearbyint Ta Fn trunc +.It Fn fdim Ta Fn lgamma Ta Fn nextafter Ta \& +.It Fn floor Ta Fn llrint Ta Fn nexttoward Ta \& +.El +.Pp +The following macros always expand to a complex function: +.Bl -column -offset indent ".Fn cimag" ".Fn cimag" ".Fn cimag" ".Fn cimag" ".Fn cimag" +.It Fn carg Ta Fn cimag Ta Fn conj Ta Fn cproj Ta Fn creal +.El +.Pp +This header includes +.In complex.h +and +.In math.h . +.Sh STANDARDS +The header +.In tgmath.h +conforms to +.St -isoC-99 . +.Sh HISTORY +The header +.In tgmath.h +first appeared in +.Fx 5.3 . +.Sh COMPILER SUPPORT +Before +.St -isoC-2011 , +the header +.In tgmath.h +could not be implemented with strictly conforming C code and needed +special compiler support. +As of +.St -isoC-2011 , +this header file can be implemented using the +.Fn _Generic +language keyword. +In addition to compilers that support this keyword, this header file +works with GCC. +.Sh BUGS +Many of the functions mentioned here are not prototyped in +.In math.h +or +.In complex.h +as they are not yet implemented. +This prevents the corresponding type-generic macro from working at all. diff --git a/static/freebsd/man3/timeradd.3 b/static/freebsd/man3/timeradd.3 new file mode 100644 index 00000000..97202678 --- /dev/null +++ b/static/freebsd/man3/timeradd.3 @@ -0,0 +1,164 @@ +.\" Copyright (c) 1999 Kelly Yancey <kbyanc@posi.net> +.\" 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 author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY JOHN BIRRELL 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 July 30, 2018 +.Dt TIMERADD 3 +.Os +.Sh NAME +.Nm timeradd , +.Nm timersub , +.Nm timerclear , +.Nm timerisset , +.Nm timercmp , +.Nm timespecadd , +.Nm timespecsub , +.Nm timespecclear , +.Nm timespecisset , +.Nm timespeccmp +.Nd operations on timevals and timespecs +.Sh SYNOPSIS +.In sys/time.h +.Ft void +.Fn timeradd "struct timeval *a" "struct timeval *b" "struct timeval *res" +.Ft void +.Fn timersub "struct timeval *a" "struct timeval *b" "struct timeval *res" +.Ft void +.Fn timerclear "struct timeval *tvp" +.Ft int +.Fn timerisset "struct timeval *tvp" +.Ft int +.Fn timercmp "struct timeval *a" "struct timeval *b" CMP +.Ft void +.Fn timespecadd "struct timespec *a" "struct timespec *b" "struct timespec *res" +.Ft void +.Fn timespecsub "struct timespec *a" "struct timespec *b" "struct timespec *res" +.Ft void +.Fn timespecclear "struct timespec *ts" +.Ft int +.Fn timespecisset "struct timespec *ts" +.Ft int +.Fn timespeccmp "struct timespec *a" "struct timespec *b" CMP +.Sh DESCRIPTION +These macros are provided for manipulating +.Fa timeval +and +.Fa timespec +structures for use with the +.Xr clock_gettime 2 , +.Xr clock_settime 2 , +.Xr gettimeofday 2 +and +.Xr settimeofday 2 +calls. +The +.Fa timeval +structure is defined in +.In sys/time.h +as: +.Bd -literal +struct timeval { + long tv_sec; /* seconds since Jan. 1, 1970 */ + long tv_usec; /* and microseconds */ +}; +.Ed +.Pp +And the +.Fa timespec +structure is defined in +.In time.h +as: +.Bd -literal +struct timespec { + time_t tv_sec; /* seconds */ + long tv_nsec; /* and nanoseconds */ +}; +.Ed +.Pp +.Fn timeradd +and +.Fn timespecadd +add the time information stored in +.Fa a +to +.Fa b +and store the result in +.Fa res . +The results are simplified such that the value of +.Fa res->tv_usec +or +.Fa res->tv_nsec +is always less than 1 second. +.Pp +.Fn timersub +and +.Fn timespecsub +subtract the time information stored in +.Fa b +from +.Fa a +and store the result +in +.Fa res . +.Pp +.Fn timerclear +and +.Fn timespecclear +initialize their argument to midnight (0 hour) January 1st, 1970 (the Epoch). +.Pp +.Fn timerisset +and +.Fn timespecisset +return true if their argument is set to any time value other than the Epoch. +.Pp +.Fn timercmp +and +.Fn timespeccmp +compare +.Fa a +to +.Fa b +using the comparison operator given in +.Fa CMP , +and return the result of that comparison. +.Sh SEE ALSO +.Xr clock_gettime 2 , +.Xr gettimeofday 2 +.Sh HISTORY +The +.Fn timeradd +family of macros were imported from +.Nx 1.1 , +and appeared in +.Fx 2.2.6 . +The +.Fn timespecadd +family of macros were imported from +.Nx 1.3 +into +.Fx 3.0 , +though they were not exposed to userland until +.Fx 12.0 . diff --git a/static/freebsd/man3/tree.3 b/static/freebsd/man3/tree.3 new file mode 100644 index 00000000..83d005a5 --- /dev/null +++ b/static/freebsd/man3/tree.3 @@ -0,0 +1,816 @@ +.\" $OpenBSD: tree.3,v 1.7 2002/06/12 01:09:20 provos Exp $ +.\" +.\" Copyright 2002 Niels Provos <provos@citi.umich.edu> +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by Niels Provos. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 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 August 2, 2024 +.Dt TREE 3 +.Os +.Sh NAME +.Nm SPLAY_PROTOTYPE , +.Nm SPLAY_GENERATE , +.Nm SPLAY_ENTRY , +.Nm SPLAY_HEAD , +.Nm SPLAY_INITIALIZER , +.Nm SPLAY_ROOT , +.Nm SPLAY_EMPTY , +.Nm SPLAY_NEXT , +.Nm SPLAY_MIN , +.Nm SPLAY_MAX , +.Nm SPLAY_FIND , +.Nm SPLAY_LEFT , +.Nm SPLAY_RIGHT , +.Nm SPLAY_FOREACH , +.Nm SPLAY_INIT , +.Nm SPLAY_INSERT , +.Nm SPLAY_REMOVE , +.Nm RB_PROTOTYPE , +.Nm RB_PROTOTYPE_STATIC , +.Nm RB_PROTOTYPE_INSERT , +.Nm RB_PROTOTYPE_INSERT_COLOR , +.Nm RB_PROTOTYPE_REMOVE , +.Nm RB_PROTOTYPE_REMOVE_COLOR , +.Nm RB_PROTOTYPE_FIND , +.Nm RB_PROTOTYPE_NFIND , +.Nm RB_PROTOTYPE_NEXT , +.Nm RB_PROTOTYPE_PREV , +.Nm RB_PROTOTYPE_MINMAX , +.Nm RB_PROTOTYPE_REINSERT , +.Nm RB_GENERATE , +.Nm RB_GENERATE_STATIC , +.Nm RB_GENERATE_INSERT , +.Nm RB_GENERATE_INSERT_COLOR , +.Nm RB_GENERATE_REMOVE , +.Nm RB_GENERATE_REMOVE_COLOR , +.Nm RB_GENERATE_FIND , +.Nm RB_GENERATE_NFIND , +.Nm RB_GENERATE_NEXT , +.Nm RB_GENERATE_PREV , +.Nm RB_GENERATE_MINMAX , +.Nm RB_GENERATE_REINSERT , +.Nm RB_ENTRY , +.Nm RB_HEAD , +.Nm RB_INITIALIZER , +.Nm RB_ROOT , +.Nm RB_EMPTY , +.Nm RB_NEXT , +.Nm RB_PREV , +.Nm RB_MIN , +.Nm RB_MAX , +.Nm RB_FIND , +.Nm RB_NFIND , +.Nm RB_LEFT , +.Nm RB_RIGHT , +.Nm RB_PARENT , +.Nm RB_FOREACH , +.Nm RB_FOREACH_FROM , +.Nm RB_FOREACH_SAFE , +.Nm RB_FOREACH_REVERSE , +.Nm RB_FOREACH_REVERSE_FROM , +.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 +.Fn SPLAY_PROTOTYPE NAME TYPE FIELD CMP +.Fn SPLAY_GENERATE NAME TYPE FIELD CMP +.Fn SPLAY_ENTRY TYPE +.Fn SPLAY_HEAD HEADNAME TYPE +.Ft "struct TYPE *" +.Fn SPLAY_INITIALIZER "SPLAY_HEAD *head" +.Fn SPLAY_ROOT "SPLAY_HEAD *head" +.Ft bool +.Fn SPLAY_EMPTY "SPLAY_HEAD *head" +.Ft "struct TYPE *" +.Fn SPLAY_NEXT NAME "SPLAY_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn SPLAY_MIN NAME "SPLAY_HEAD *head" +.Ft "struct TYPE *" +.Fn SPLAY_MAX NAME "SPLAY_HEAD *head" +.Ft "struct TYPE *" +.Fn SPLAY_FIND NAME "SPLAY_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn SPLAY_LEFT "struct TYPE *elm" "SPLAY_ENTRY NAME" +.Ft "struct TYPE *" +.Fn SPLAY_RIGHT "struct TYPE *elm" "SPLAY_ENTRY NAME" +.Fn SPLAY_FOREACH VARNAME NAME "SPLAY_HEAD *head" +.Ft void +.Fn SPLAY_INIT "SPLAY_HEAD *head" +.Ft "struct TYPE *" +.Fn SPLAY_INSERT NAME "SPLAY_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn SPLAY_REMOVE NAME "SPLAY_HEAD *head" "struct TYPE *elm" +.Fn RB_PROTOTYPE NAME TYPE FIELD CMP +.Fn RB_PROTOTYPE_STATIC NAME TYPE FIELD CMP +.Fn RB_PROTOTYPE_INSERT NAME TYPE ATTR +.Fn RB_PROTOTYPE_INSERT_COLOR NAME TYPE ATTR +.Fn RB_PROTOTYPE_REMOVE NAME TYPE ATTR +.Fn RB_PROTOTYPE_REMOVE_COLOR NAME TYPE ATTR +.Fn RB_PROTOTYPE_FIND NAME TYPE ATTR +.Fn RB_PROTOTYPE_NFIND NAME TYPE ATTR +.Fn RB_PROTOTYPE_NEXT NAME TYPE ATTR +.Fn RB_PROTOTYPE_PREV NAME TYPE ATTR +.Fn RB_PROTOTYPE_MINMAX NAME TYPE ATTR +.Fn RB_PROTOTYPE_REINSERT NAME TYPE ATTR +.Fn RB_GENERATE NAME TYPE FIELD CMP +.Fn RB_GENERATE_STATIC NAME TYPE FIELD CMP +.Fn RB_GENERATE_INSERT NAME TYPE FIELD CMP ATTR +.Fn RB_GENERATE_INSERT_COLOR NAME TYPE FIELD ATTR +.Fn RB_GENERATE_REMOVE NAME TYPE FIELD ATTR +.Fn RB_GENERATE_REMOVE_COLOR NAME TYPE FIELD ATTR +.Fn RB_GENERATE_FIND NAME TYPE FIELD CMP ATTR +.Fn RB_GENERATE_NFIND NAME TYPE FIELD CMP ATTR +.Fn RB_GENERATE_NEXT NAME TYPE FIELD ATTR +.Fn RB_GENERATE_PREV NAME TYPE FIELD ATTR +.Fn RB_GENERATE_MINMAX NAME TYPE FIELD ATTR +.Fn RB_GENERATE_REINSERT NAME TYPE FIELD CMP ATTR +.Fn RB_ENTRY TYPE +.Fn RB_HEAD HEADNAME TYPE +.Fn RB_INITIALIZER "RB_HEAD *head" +.Ft "struct TYPE *" +.Fn RB_ROOT "RB_HEAD *head" +.Ft "bool" +.Fn RB_EMPTY "RB_HEAD *head" +.Ft "struct TYPE *" +.Fn RB_NEXT NAME "RB_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn RB_PREV NAME "RB_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn RB_MIN NAME "RB_HEAD *head" +.Ft "struct TYPE *" +.Fn RB_MAX NAME "RB_HEAD *head" +.Ft "struct TYPE *" +.Fn RB_FIND NAME "RB_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn RB_NFIND NAME "RB_HEAD *head" "struct TYPE *elm" +.Ft "struct TYPE *" +.Fn RB_LEFT "struct TYPE *elm" "RB_ENTRY NAME" +.Ft "struct TYPE *" +.Fn RB_RIGHT "struct TYPE *elm" "RB_ENTRY NAME" +.Ft "struct TYPE *" +.Fn RB_PARENT "struct TYPE *elm" "RB_ENTRY NAME" +.Fn RB_FOREACH VARNAME NAME "RB_HEAD *head" +.Fn RB_FOREACH_FROM "VARNAME" "NAME" "POS_VARNAME" +.Fn RB_FOREACH_SAFE "VARNAME" "NAME" "RB_HEAD *head" "TEMP_VARNAME" +.Fn RB_FOREACH_REVERSE VARNAME NAME "RB_HEAD *head" +.Fn RB_FOREACH_REVERSE_FROM "VARNAME" "NAME" "POS_VARNAME" +.Fn RB_FOREACH_REVERSE_SAFE "VARNAME" "NAME" "RB_HEAD *head" "TEMP_VARNAME" +.Ft void +.Fn RB_INIT "RB_HEAD *head" +.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. +.Pp +In the macro definitions, +.Fa TYPE +is the name tag of a user defined structure that must contain a field of type +.Vt SPLAY_ENTRY , +or +.Vt RB_ENTRY , +named +.Fa ENTRYNAME . +The argument +.Fa HEADNAME +is the name tag of a user defined structure that must be declared +using the macros +.Fn SPLAY_HEAD , +or +.Fn RB_HEAD . +The argument +.Fa NAME +has to be a unique name prefix for every tree that is defined. +.Pp +The function prototypes are declared with +.Fn SPLAY_PROTOTYPE , +.Fn RB_PROTOTYPE , +or +.Fn RB_PROTOTYPE_STATIC . +The function bodies are generated with +.Fn SPLAY_GENERATE , +.Fn RB_GENERATE , +or +.Fn RB_GENERATE_STATIC . +See the examples below for further explanation of how these macros are used. +.Sh SPLAY TREES +A splay tree is a self-organizing data structure. +Every operation on the tree causes a splay to happen. +The splay moves the requested +node to the root of the tree and partly rebalances it. +.Pp +This has the benefit that request locality causes faster lookups as +the requested nodes move to the top of the tree. +On the other hand, every lookup causes memory writes. +.Pp +The Balance Theorem bounds the total access time for +.Ar m +operations and +.Ar n +inserts on an initially empty tree as +.Fn O "\*[lp]m + n\*[rp]lg n" . +The +amortized cost for a sequence of +.Ar m +accesses to a splay tree is +.Fn O "lg n" . +.Pp +A splay tree is headed by a structure defined by the +.Fn SPLAY_HEAD +macro. +A +structure is declared as follows: +.Bd -ragged -offset indent +.Fn SPLAY_HEAD HEADNAME TYPE +.Va head ; +.Ed +.Pp +where +.Fa HEADNAME +is the name of the structure to be defined, and struct +.Fa TYPE +is the type of the elements to be inserted into the tree. +.Pp +The +.Fn SPLAY_ENTRY +macro declares a structure that allows elements to be connected in the tree. +.Pp +In order to use the functions that manipulate the tree structure, +their prototypes need to be declared with the +.Fn SPLAY_PROTOTYPE +macro, +where +.Fa NAME +is a unique identifier for this particular tree. +The +.Fa TYPE +argument is the type of the structure that is being managed +by the tree. +The +.Fa FIELD +argument is the name of the element defined by +.Fn SPLAY_ENTRY . +.Pp +The function bodies are generated with the +.Fn SPLAY_GENERATE +macro. +It takes the same arguments as the +.Fn SPLAY_PROTOTYPE +macro, but should be used only once. +.Pp +Finally, +the +.Fa CMP +argument is the name of a function used to compare tree nodes +with each other. +The function takes two arguments of type +.Vt "struct TYPE *" . +If the first argument is smaller than the second, the function returns a +value smaller than zero. +If they are equal, the function returns zero. +Otherwise, it should return a value greater than zero. +The compare +function defines the order of the tree elements. +.Pp +The +.Fn SPLAY_INIT +macro initializes the tree referenced by +.Fa head . +.Pp +The splay tree can also be initialized statically by using the +.Fn SPLAY_INITIALIZER +macro like this: +.Bd -ragged -offset indent +.Fn SPLAY_HEAD HEADNAME TYPE +.Va head += +.Fn SPLAY_INITIALIZER &head ; +.Ed +.Pp +The +.Fn SPLAY_INSERT +macro inserts the new element +.Fa elm +into the tree. +.Pp +The +.Fn SPLAY_REMOVE +macro removes the element +.Fa elm +from the tree pointed by +.Fa head . +.Pp +The +.Fn SPLAY_FIND +macro can be used to find a particular element in the tree. +.Bd -literal -offset indent +struct TYPE find, *res; +find.key = 30; +res = SPLAY_FIND(NAME, head, &find); +.Ed +.Pp +The +.Fn SPLAY_ROOT , +.Fn SPLAY_MIN , +.Fn SPLAY_MAX , +and +.Fn SPLAY_NEXT +macros can be used to traverse the tree: +.Bd -literal -offset indent +for (np = SPLAY_MIN(NAME, &head); np != NULL; np = SPLAY_NEXT(NAME, &head, np)) +.Ed +.Pp +Or, for simplicity, one can use the +.Fn SPLAY_FOREACH +macro: +.Bd -ragged -offset indent +.Fn SPLAY_FOREACH np NAME head +.Ed +.Pp +The +.Fn SPLAY_EMPTY +macro should be used to check whether a splay tree is empty. +.Sh RANK-BALANCED TREES +Rank-balanced (RB) trees are a framework for defining height-balanced +binary search trees, including AVL and red-black trees. +Each tree node has an associated rank. +Balance conditions are expressed by conditions on the differences in +rank between any node and its children. +Rank differences are stored in each tree node. +.Pp +The balance conditions implemented by the RB macros lead to weak AVL +(wavl) trees, which combine the best aspects of AVL and red-black +trees. +Wavl trees rebalance after an insertion in the same way AVL trees do, +with the same worst-case time as red-black trees offer, and with +better balance in the resulting tree. +Wavl trees rebalance after a removal in a way that requires less +restructuring, in the worst case, than either AVL or red-black trees +do. +Removals can lead to a tree almost as unbalanced as a red-black +tree; insertions lead to a tree becoming as balanced as an AVL tree. +.Pp +A rank-balanced tree is headed by a structure defined by the +.Fn RB_HEAD +macro. +A +structure is declared as follows: +.Bd -ragged -offset indent +.Fn RB_HEAD HEADNAME TYPE +.Va head ; +.Ed +.Pp +where +.Fa HEADNAME +is the name of the structure to be defined, and struct +.Fa TYPE +is the type of the elements to be inserted into the tree. +.Pp +The +.Fn RB_ENTRY +macro declares a structure that allows elements to be connected in the tree. +.Pp +In order to use the functions that manipulate the tree structure, +their prototypes need to be declared with the +.Fn RB_PROTOTYPE +or +.Fn RB_PROTOTYPE_STATIC +macro, +where +.Fa NAME +is a unique identifier for this particular tree. +The +.Fa TYPE +argument is the type of the structure that is being managed +by the tree. +The +.Fa FIELD +argument is the name of the element defined by +.Fn RB_ENTRY . +Individual prototypes can be declared with +.Fn RB_PROTOTYPE_INSERT , +.Fn RB_PROTOTYPE_INSERT_COLOR , +.Fn RB_PROTOTYPE_REMOVE , +.Fn RB_PROTOTYPE_REMOVE_COLOR , +.Fn RB_PROTOTYPE_FIND , +.Fn RB_PROTOTYPE_NFIND , +.Fn RB_PROTOTYPE_NEXT , +.Fn RB_PROTOTYPE_PREV , +.Fn RB_PROTOTYPE_MINMAX , +and +.Fn RB_PROTOTYPE_REINSERT +in case not all functions are required. +The individual prototype macros expect +.Fa NAME , +.Fa TYPE , +and +.Fa ATTR +arguments. +The +.Fa ATTR +argument must be empty for global functions or +.Fa static +for static functions. +.Pp +The function bodies are generated with the +.Fn RB_GENERATE +or +.Fn RB_GENERATE_STATIC +macro. +These macros take the same arguments as the +.Fn RB_PROTOTYPE +and +.Fn RB_PROTOTYPE_STATIC +macros, but should be used only once. +As an alternative individual function bodies are generated with the +.Fn RB_GENERATE_INSERT , +.Fn RB_GENERATE_INSERT_COLOR , +.Fn RB_GENERATE_REMOVE , +.Fn RB_GENERATE_REMOVE_COLOR , +.Fn RB_GENERATE_FIND , +.Fn RB_GENERATE_NFIND , +.Fn RB_GENERATE_NEXT , +.Fn RB_GENERATE_PREV , +.Fn RB_GENERATE_MINMAX , +and +.Fn RB_GENERATE_REINSERT +macros. +.Pp +Finally, +the +.Fa CMP +argument is the name of a function used to compare tree nodes +with each other. +The function takes two arguments of type +.Vt "struct TYPE *" . +If the first argument is smaller than the second, the function returns a +value smaller than zero. +If they are equal, the function returns zero. +Otherwise, it should return a value greater than zero. +The compare +function defines the order of the tree elements. +.Pp +The +.Fn RB_INIT +macro initializes the tree referenced by +.Fa head . +.Pp +The rank-balanced tree can also be initialized statically by using the +.Fn RB_INITIALIZER +macro like this: +.Bd -ragged -offset indent +.Fn RB_HEAD HEADNAME TYPE +.Va head += +.Fn RB_INITIALIZER &head ; +.Ed +.Pp +The +.Fn RB_INSERT +macro inserts the new element +.Fa elm +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 +from the tree pointed by +.Fa head . +.Pp +The +.Fn RB_FIND +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, *resn; +find.key = 30; +res = RB_FIND(NAME, head, &find); +resn = RB_NFIND(NAME, head, &find); +.Ed +.Pp +The +.Fn RB_ROOT , +.Fn RB_MIN , +.Fn RB_MAX , +.Fn RB_NEXT , +and +.Fn RB_PREV +macros can be used to traverse the tree: +.Pp +.Dl "for (np = RB_MIN(NAME, &head); np != NULL; np = RB_NEXT(NAME, &head, np))" +.Pp +Or, for simplicity, one can use the +.Fn RB_FOREACH +or +.Fn RB_FOREACH_REVERSE +macro: +.Bd -ragged -offset indent +.Fn RB_FOREACH np NAME head +.Ed +.Pp +The macros +.Fn RB_FOREACH_SAFE +and +.Fn RB_FOREACH_REVERSE_SAFE +traverse the tree referenced by head +in a forward or reverse direction respectively, +assigning each element in turn to np. +However, unlike their unsafe counterparts, +they permit both the removal of np +as well as freeing it from within the loop safely +without interfering with the traversal. +.Pp +Both +.Fn RB_FOREACH_FROM +and +.Fn RB_FOREACH_REVERSE_FROM +may be used to continue an interrupted traversal +in a forward or reverse direction respectively. +The head pointer is not required. +The pointer to the node from where to resume the traversal +should be passed as their last argument, +and will be overwritten to provide safe traversal. +.Pp +The +.Fn RB_EMPTY +macro should be used to check whether a rank-balanced tree is empty. +.Pp +The +.Fn RB_REINSERT +macro updates the position of the element +.Fa elm +in the tree. +This must be called if a member of a +.Nm tree +is modified in a way that affects comparison, such as by modifying +a node's key. +This is a lower overhead alternative to removing the element +and reinserting it again. +.Pp +The +.Fn RB_AUGMENT +macro updates augmentation data of the element +.Fa elm +in the tree. +By default, it has no effect. +It is not meant to be invoked by the RB user. +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. +Values are inserted into it and the contents of the tree are printed +in order. +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> +#include <stdlib.h> + +struct node { + RB_ENTRY(node) entry; + int i, sum; +}; + +int +intcmp(struct node *e1, struct node *e2) +{ + return (e1->i < e2->i ? -1 : e1->i > e2->i); +} + +void +sumaug(struct node *e) +{ + e->sum = e->i; + if (RB_LEFT(e, entry) != NULL) + e->sum += RB_LEFT(e, entry)->sum; + if (RB_RIGHT(e, entry) != NULL) + e->sum += RB_RIGHT(e, entry)->sum; +} + +RB_HEAD(inttree, node) head = RB_INITIALIZER(&head); +RB_GENERATE(inttree, node, entry, intcmp) + +int testdata[] = { + 20, 16, 17, 13, 3, 6, 1, 8, 2, 4, 10, 19, 5, 9, 12, 15, 18, + 7, 11, 14 +}; + +void +print_tree(struct node *n) +{ + struct node *left, *right; + + if (n == NULL) { + printf("nil"); + return; + } + left = RB_LEFT(n, entry); + right = RB_RIGHT(n, entry); + if (left == NULL && right == NULL) + printf("%d", n->i); + else { + printf("%d(", n->i); + print_tree(left); + printf(","); + print_tree(right); + printf(")"); + } +} + +int +main(void) +{ + int i; + struct node *n; + + for (i = 0; i < sizeof(testdata) / sizeof(testdata[0]); i++) { + if ((n = malloc(sizeof(struct node))) == NULL) + err(1, NULL); + n->i = testdata[i]; + RB_INSERT(inttree, &head, n); + } + + RB_FOREACH(n, inttree, &head) { + printf("%d\en", n->i); + } + print_tree(RB_ROOT(&head)); + printf("\enSum of values = %d\en", RB_ROOT(&head)->sum); + return (0); +} +.Ed +.Sh NOTES +Trying to free a tree in the following way is a common error: +.Bd -literal -offset indent +SPLAY_FOREACH(var, NAME, head) { + SPLAY_REMOVE(NAME, head, var); + free(var); +} +free(head); +.Ed +.Pp +Since +.Va var +is freed, the +.Fn FOREACH +macro refers to a pointer that may have been reallocated already. +Proper code needs a second variable. +.Bd -literal -offset indent +for (var = SPLAY_MIN(NAME, head); var != NULL; var = nxt) { + nxt = SPLAY_NEXT(NAME, head, var); + SPLAY_REMOVE(NAME, head, var); + free(var); +} +.Ed +.Pp +Both +.Fn RB_INSERT +and +.Fn SPLAY_INSERT +return +.Dv NULL +if the element was inserted in the tree successfully, otherwise they +return a pointer to the element with the colliding key. +.Pp +Accordingly, +.Fn RB_REMOVE +and +.Fn SPLAY_REMOVE +return the pointer to the removed element otherwise they return +.Dv NULL +to indicate an error. +.Sh SEE ALSO +.Xr arb 3 , +.Xr queue 3 +.Rs +.%A "Bernhard Haeupler" +.%A "Siddhartha Sen" +.%A "Robert E. Tarjan" +.%T "Rank-Balanced Trees" +.%U "http://sidsen.azurewebsites.net/papers/rb-trees-talg.pdf" +.%J "ACM Transactions on Algorithms" +.%V "11" +.%N "4" +.%D "June 2015" +.Re +.Sh HISTORY +The tree macros first appeared in +.Fx 4.6 . +.Sh AUTHORS +The author of the tree macros is +.An Niels Provos . |
