diff options
Diffstat (limited to 'static/netbsd/man3')
57 files changed, 9667 insertions, 0 deletions
diff --git a/static/netbsd/man3/CMSG_DATA.3 b/static/netbsd/man3/CMSG_DATA.3 new file mode 100644 index 00000000..f755e147 --- /dev/null +++ b/static/netbsd/man3/CMSG_DATA.3 @@ -0,0 +1,188 @@ +.\" $NetBSD: CMSG_DATA.3,v 1.6 2025/03/26 14:12:16 riastradh Exp $ +.\" $OpenBSD: CMSG_DATA.3,v 1.5 2008/03/24 16:11:07 deraadt Exp $ +.\" Written by Jared Yanovich <jaredy@openbsd.org> +.\" Public domain, July 3, 2005 +.Dd January 24, 2015 +.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 +.Sh SYNOPSIS +.In sys/socket.h +.Ft unsigned char * +.Fn CMSG_DATA "struct cmsghdr *" +.Ft const unsigned char * +.Fn CCMSG_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 mhdr +This routine accesses the first control message attached to the +message +.Fa msg . +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. +.Pp +This value is what is normally stored in the +.Fa cmsg_len +of each control message. +.Pp +This routine accounts for any alignment constraints on the beginning of +ancillary data. +.Pp +If +.Fa len +is an integer constant expression, then +.Fn CMSG_LEN len +is an integer constant expression. +.It Fn CMSG_NXTHDR mhdr cmsg +This routine returns the location of the control message following +.Fa cmsg +in the message +.Fa mhdr . +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. +.Pp +This value is what is normally stored in +.Fa msg_msgcontrollen . +.Pp +This routine accounts for any alignment constraints on the beginning of +ancillary data as well as any needed to pad the next control message. +.Pp +If +.Fa len +is an integer constant expression, then +.Fn CMSG_SPACE len +is an integer constant expression. +.El +.Sh EXAMPLES +The following example constructs a control message containing a file +descriptor and passes it over a socket: +.Bd -literal -offset indent +struct msghdr msg; +struct cmsghdr *cmsg; +/* We use a union to make sure hdr is aligned */ +union { + struct cmsghdr hdr; + unsigned char buf[CMSG_SPACE(sizeof(int))]; +} cmsgbuf; + +(void)memset(&msg, 0, sizeof(msg)); +msg.msg_control = cmsgbuf.buf; +msg.msg_controllen = sizeof(cmsgbuf.buf); + +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) = fd; + +if (sendmsg(s, &msg, 0) == -1) + err(1, "sendmsg"); +.Ed +.Pp +And an example that receives the control message and handles all the +file descriptors it receives: +.Bd -literal -offset indent +struct msghdr msg; +struct cmsghdr *cmsg; +union { + struct cmsghdr hdr; + unsigned char buf[CMSG_SPACE(sizeof(int))]; +} cmsgbuf; + +(void)memset(&msg, 0, sizeof(msg)); +msg.msg_control = cmsgbuf.buf; +msg.msg_controllen = sizeof(cmsgbuf.buf); + +if (recvmsg(s, &msg, 0) == -1) + err(1, "recvmsg"); +if (msg.msg_flags & MSG_CTRUNC) + warnx("control message truncated"); +for (cmsg = CMSG_FIRSTHDR(&msg); cmsg != NULL; + cmsg = CMSG_NXTHDR(&msg, cmsg)) { + if (cmsg->cmsg_level == SOL_SOCKET && + cmsg->cmsg_type == SCM_RIGHTS) { + int *fdp = (int *)CMSG_DATA(cmsg); + socklen_t nbytes = cmsg->cmsg_len - CMSG_LEN(0); + socklen_t nfds = nbytes/sizeof(fdp[0]); + + assert(nbytes % sizeof(fdp[0]) == 0); + + while (nfds --> 0) { + int fd = *fdp++; + + /* Do something with the descriptor. */ + } + } +} +.Ed +.Pp +Note that even if the receiver +.Em intends +to size its control buffer for +.Em one +file descriptor with +.Li CMSG_SPACE(sizeof(int)) , +this size may be rounded up for alignment to enough space for more than +one file descriptor. +So if the sender may send more than one file descriptor at a time, the +receiver cannot restrict itself to receiving at most one at a time, and +must be prepared to handle all of them \(em otherwise they will simply +leak on the receiver side. +.Sh SEE ALSO +.Xr recvmsg 2 , +.Xr sendmsg 2 , +.Xr socket 2 +.Sh HISTORY +The control message API first appeared in +.Bx 4.2 . diff --git a/static/netbsd/man3/Makefile b/static/netbsd/man3/Makefile new file mode 100644 index 00000000..b3d61c4b --- /dev/null +++ b/static/netbsd/man3/Makefile @@ -0,0 +1,4 @@ +MAN = $(wildcard *.3) + +include ../../mandoc.mk + diff --git a/static/netbsd/man3/_DIAGASSERT.3 b/static/netbsd/man3/_DIAGASSERT.3 new file mode 100644 index 00000000..4df491b9 --- /dev/null +++ b/static/netbsd/man3/_DIAGASSERT.3 @@ -0,0 +1,130 @@ +.\" $NetBSD: _DIAGASSERT.3,v 1.8 2008/04/30 13:10:53 martin Exp $ +.\" +.\" Copyright (c) 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Luke Mewburn. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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, 2007 +.Dt _DIAGASSERT 3 +.Os +.Sh NAME +.Nm _DIAGASSERT +.Nd expression verification macro +.Sh SYNOPSIS +.In assert.h +.Fn _DIAGASSERT expression +.Sh DESCRIPTION +The +.Fn _DIAGASSERT +macro tests the given +.Ar expression +and if it is false, one or more of the following may occur: +.Bl -bullet -offset indent +.It +a diagnostic message may be logged to the system logger with +.Xr syslog 3 . +This is default behaviour. +.It +a diagnostic message may be printed to the +.Dv stderr +stream. +.It +the calling process will be terminated by calling +.Xr abort 3 . +.El +.Pp +This behaviour may be changed by setting the +.Ev LIBC_DIAGASSERT +environment variable (see below). +.Pp +The diagnostic message consists of the text of the expression, +the name of the source file, the line number and the enclosing +function. +.Pp +If +.Ar expression +is true, +the +.Fn _DIAGASSERT +macro does nothing. +.Pp +The +.Fn _DIAGASSERT +macro is not compiled in by default, and will only be compiled in with the +.Xr cc 1 +option +.Fl D_DIAGNOSTIC . +.Pp +This macro is used in the various system libraries such as the +.Lb libc +to ensure that various library calls are invoked with valid arguments. +.Sh ENVIRONMENT +The +.Ev LIBC_DIAGASSERT +environment variable can be used to modify the default behaviour of +logging the assertion to the system logger. +.Pp +.Ev LIBC_DIAGASSERT +may be set to one or more of the following characters: +.Bl -tag -width xxx -offset indent +.It a +.Xr abort 3 +once any assertion messages have been logged and/or printed. +.It A +Opposite of +.Dq a . +.It e +Print the assertion message to the +.Dv stderr +stream. +.It E +Opposite of +.Dq e . +.It l +Log the assertion message with +.Xr syslog 3 +to the facility +.Dv user.debug . +.It L +Opposite of +.Dq l . +.El +.Sh DIAGNOSTICS +The diagnostic message has the following format: +.Bd -literal -offset indent +"assertion \e"%s\e" failed: file \e"%s\e", line %d, function \e"%s\e"\en", + "expression", __FILE__, __LINE__, __func__ +.Ed +.Sh SEE ALSO +.Xr cc 1 , +.Xr abort 3 , +.Xr assert 3 , +.Xr syslog 3 +.Sh HISTORY +The +.Nm _DIAGASSERT +macro appeared in +.Nx 1.5 . diff --git a/static/netbsd/man3/__CONCAT.3 b/static/netbsd/man3/__CONCAT.3 new file mode 100644 index 00000000..fd99a81c --- /dev/null +++ b/static/netbsd/man3/__CONCAT.3 @@ -0,0 +1,108 @@ +.\" $NetBSD: __CONCAT.3,v 1.8 2013/10/17 20:43:49 wiz Exp $ $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 17, 2013 +.Dt __CONCAT 3 +.Os +.Sh NAME +.Nm __CONCAT , +.Nm __STRING +.Nd argument substitution +.Sh SYNOPSIS +.In sys/cdefs.h +.Ft xy +.Fn __CONCAT "x" "y" +.Ft const char * +.Fn __STRING "x" +.Sh DESCRIPTION +The +.Nm +macro makes use of the +.Xr cpp 1 +preprocessor to concatenate two tokens. +When the macro is expanded, +.Fa x +and +.Fa y +are combined into a single token, provided that the result forms a valid token; +two tokens that together do not form a valid token can not be concatenated. +This is known as +.Dq token concatenation +or +.Dq token pasting . +.Pp +The +.Fn __STRING +macro uses the conventional +.Sq # +preprocessing operator to replace the argument +.Fa x +with a string literal. +This is also known as +.Dq stringification . +.Sh EXAMPLES +The following two +.Xr printf 3 +calls produce the same output: +.Bd -literal -offset indent +#define Net 0x01 +#define BSD 0x02 + +#define NetBSD "NetBSD" + +(void)printf("%s\en", __CONCAT(Net, BSD)); +(void)printf("%s%s\en", __STRING(Net), __STRING(BSD)); +.Ed +.Sh SEE ALSO +.Xr cpp 1 , +.Xr cdefs 3 +.Sh HISTORY +The +.Fn __CONCAT +and +.Fn __STRING +macros first appeared in +.Nx 1.3 . +.Sh CAVEATS +Many small details direct the proper use of the macros. +For example, while all leading and trailing whitespace is ignored when +.Fn __STRING +is used, it is undefined whether +.Xr cpp 1 +puts white space between the tokens when +.Fn __CONCAT +is used. +It can be also noted that the C preprocessor converts all +comments to whitespace before any macros are even considered. +The use of either macro is discouraged in complex constructs. +.Pp +Use of this macro is non-portable; this is part of the implementation +namespace and should only be used in +.Nx +code. diff --git a/static/netbsd/man3/__FPTRCAST.3 b/static/netbsd/man3/__FPTRCAST.3 new file mode 100644 index 00000000..4c6d5ed2 --- /dev/null +++ b/static/netbsd/man3/__FPTRCAST.3 @@ -0,0 +1,80 @@ +.\" $NetBSD: __FPTRCAST.3,v 1.2 2019/11/11 11:06:27 wiz Exp $ $ +.\" +.\" Copyright (c) 2019 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 17, 2013 +.Dt __FPTRCAST 3 +.Os +.Sh NAME +.Nm __FPTRCAST +.Nd function pointer cast +.Sh SYNOPSIS +.In sys/cdefs.h +.Ft ftype +.Fn __FPTRCAST ftype fname +.Sh DESCRIPTION +The +.Fn __FPTRCAST +macro can be used to silence warnings produced by certain compilers when +converting from one function pointer type to another. +The +.Fa ftype +argument is the function pointer type to which to cast the function +pointer in +.Fa fname . +.Pp +This cast should be used sparingly and it is typically used in the following +situations: +.Bl -bullet -offset indent -compact +.It +We know that the function prototypes don't match at all, but we don't care +because we point it to a function that does not take arguments and returns +an error. +.It +We only care about the first few arguments and we don't care about the rest. +.It +We don't care about the return value, we ignore it anyway. +.El +.Sh IMPLEMENTATION NOTES +This macro is implemented by using an intermediate +.Em void * +cast. +.Sh SEE ALSO +.Xr cc 1 , +.Xr cdefs 3 +.Sh CAVEATS +Use of this macro can hide valid errors, and its usage is not recommended +unless there is a well-thought reason for a cast. +As a general guideline, don't use this macro inside other macros because +it will hide cases where the user of the original macro accidentally used +an incorrect function pointer. +.Pp +Use of this macro is non-portable; this is part of the implementation +namespace and should only be used in +.Nx +code. diff --git a/static/netbsd/man3/__UNCONST.3 b/static/netbsd/man3/__UNCONST.3 new file mode 100644 index 00000000..32f73647 --- /dev/null +++ b/static/netbsd/man3/__UNCONST.3 @@ -0,0 +1,88 @@ +.\" $NetBSD: __UNCONST.3,v 1.7 2013/10/17 20:43:49 wiz Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 17, 2013 +.Dt __UNCONST 3 +.Os +.Sh NAME +.Nm __UNCONST +.Nd compile time cast-away macro +.Sh SYNOPSIS +.In sys/cdefs.h +.Ft void +.Fn __UNCONST x +.Ft void +.Fn __UNVOLATILE x +.Sh DESCRIPTION +The +.Fn __UNCONST +macro can be used to omit warnings produced by certain compilers when +operating with pointers declared with the +.Em const +type qualifier in a context without such qualifier. +Examples include passing a pointer declared with the +.Em const +qualifier to a function without such qualifier, +and variable assignment from a +.Em const +pointer to a non-const pointer. +In the same vein, the +.Fn __UNVOLATILE +macro can be used to exclude warnings related to the +.Em volatile +type qualifier. +.Sh IMPLEMENTATION NOTES +These macros are implemented by explicitly using +.Em unsigned long +instead of +.Em intptr_t , +a signed type guaranteed to hold a pointer. +.Sh SEE ALSO +.Xr cc 1 , +.Xr cdefs 3 +.Sh CAVEATS +As both macros may hide valid errors, their usage is not recommended +unless there is a well-thought reason for a cast. +A typical use case for +.Fn __UNCONST +involve an +.Tn API +that does not follow the so-called ``const correctness'' +even if it would be appropriate. +Valid use cases of +.Fn __UNVOLATILE +include passing a +.Em volatile +pointer to +.Xr memset 3 . +.Pp +Use of this macro is non-portable; this is part of the implementation +namespace and should only be used in +.Nx +code. diff --git a/static/netbsd/man3/__USE.3 b/static/netbsd/man3/__USE.3 new file mode 100644 index 00000000..d32df999 --- /dev/null +++ b/static/netbsd/man3/__USE.3 @@ -0,0 +1,122 @@ +.\" $NetBSD: __USE.3,v 1.2 2013/10/17 19:37:56 jnemeth Exp $ +.\" +.\" Copyright (c) 2013 The NetBSD Foundation, 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. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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 17, 2013 +.Dt __USE 3 +.Os +.Sh NAME +.Nm __USE +.Nd compile time macro that marks a variable as being used +.Sh SYNOPSIS +.In sys/cdefs.h +.Ft void +.Fn __USE x +.Sh DESCRIPTION +The +.Nm __USE +macro can be used to omit warnings produced by certain compilers when +variables are being set, but not used in a function. +.Pp +There are cases where it is simpler to mark a variable as used, as opposed +to ifdef out its use: +.Bd -literal -offset indent +#ifdef DEBUG_FOO +#define DPRINTF(a) printf a +#else +#define DPRINTF(a) + +void +foo(void) { + int var; + + var = getval(); + + DPRINTF(("val is %d\n", var)); +} +.Ed +.Pp +In this case, ifdefing the code would make it: +.Bd -literal -offset indent +void +foo(void) { +#ifdef DEBUG_FOO + int var; + + var = getval(); + + DPRINTF(("val is %d\n", var)); +#else + (void)getval(); +#endif +} +.Ed +.Pp +This is not desirable because it duplicates code. +With the +.Nm __USE +macro this can be written as: +.Bd -literal -offset indent +void +foo(void) { + int var; + + var = getval(); + +#ifdef DEBUG_FOO + DPRINTF(("val is %d\n", var)); +#else + __USE(var); +#endif +} +.Ed +.Pp +without producing compiler warnings. +.Pp +Although it is simple to write: +.Bd -literal -offset indent + (void)var; +.Ed +.Pp +abstracting this into the macro allows for alternate implementations, +as well as changing it to an empty implementation so that the liveness +of the variable can be re-evaluated. +.Sh IMPLEMENTATION NOTES +.Nm +is implemented as: +.Bd -literal -offset indent +#define __USE(a) ((void)(a)) +.Ed +.Sh SEE ALSO +.Xr cc 1 , +.Xr cdefs 3 +.Sh CAVEATS +.Nm +should be used sparingly as it can cause valid warnings to be hidden. +.Pp +Use of this macro is non-portable; this is part of the implementation +namespace and should only be used in +.Nx +code. diff --git a/static/netbsd/man3/__alignof__.3 b/static/netbsd/man3/__alignof__.3 new file mode 100644 index 00000000..b61b9bdb --- /dev/null +++ b/static/netbsd/man3/__alignof__.3 @@ -0,0 +1,84 @@ +.\" $NetBSD: __alignof__.3,v 1.5 2011/04/14 06:56:28 wiz Exp $ +.\" +.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@iki.fi> +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 20, 2010 +.Dt __ALIGNOF__ 3 +.Os +.Sh NAME +.Nm __alignof__ +.Nd GNU extension for alignment of an object +.Sh SYNOPSIS +.Ft int +.Fn __alignof__ "void x" +.Sh DESCRIPTION +The +.Fn __alignof__ +operator returns the alignment of its operand. +The operand can be a type or an expression. +If the operand is a +.Sq lvalue , +the return value represents the required alignment of the underlying type, +not the actual alignment of the specified +.Sq lvalue . +.Pp +The returned value is specific to the architecture and the +.Tn ABI . +If the architecture does not impose strict alignment requirements, +.Fn __alignof__ +returns the minimum required alignment. +If +.Xr __aligned 3 +is used to increase the alignment, +.Fn __alignof__ +returns the specified alignment. +.Sh EXAMPLES +The syntax is comparable to the +.Fn sizeof +operator. +If the architecture aligns integers along 32-bit address boundaries, +the following should print the value 4. +.Bd -literal -offset indent +(void)printf("%d\en", __alignof__(int)); +.Ed +.Pp +On the other hand, the following example should print the value 1, +even though this is unlikely to be the actual alignment of the +structure member. +.Bd -literal -offset indent +struct align { + int x; + char y; +} a; + +(void)printf("%d\en", __alignof__(a.y)); +.Ed +.Sh SEE ALSO +.Xr gcc 1 , +.Xr attribute 3 , +.Xr offsetof 3 , +.Xr typeof 3 +.Sh CAVEATS +This is a non-standard, compiler-specific extension. diff --git a/static/netbsd/man3/__arraycount.3 b/static/netbsd/man3/__arraycount.3 new file mode 100644 index 00000000..61b9ce47 --- /dev/null +++ b/static/netbsd/man3/__arraycount.3 @@ -0,0 +1,62 @@ +.\" $NetBSD: __arraycount.3,v 1.7 2017/07/03 21:30:58 wiz Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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, 2010 +.Dt __ARRAYCOUNT 3 +.Os +.Sh NAME +.Nm __arraycount +.Nd macro for statically allocated arrays +.Sh SYNOPSIS +.In sys/cdefs.h +.Ft size_t +.Fn __arraycount x +.Sh DESCRIPTION +The +.Fn __arraycount +macro returns the number of elements in a statically allocated buffer. +.Sh EXAMPLES +The following example demonstrates a typical usage of +.Fn __arraycount : +.Bd -literal -offset indent +uint8_t buf[BUFSIZE]; +size_t i; + +\&... + +for (i = 0; i < __arraycount(buf); i++) + \&... +.Ed +.Sh SEE ALSO +.Xr cdefs 3 +.Sh HISTORY +The +.Fn __arraycount +macro first appeared in +.Nx 4.0 . diff --git a/static/netbsd/man3/__builtin_constant_p.3 b/static/netbsd/man3/__builtin_constant_p.3 new file mode 100644 index 00000000..2083c122 --- /dev/null +++ b/static/netbsd/man3/__builtin_constant_p.3 @@ -0,0 +1,78 @@ +.\" $NetBSD: __builtin_constant_p.3,v 1.2 2010/12/19 10:08:44 jruoho Exp $ +.\" +.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@iki.fi> +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 19, 2010 +.Dt __BUILTIN_CONSTANT_P 3 +.Os +.Sh NAME +.Nm __builtin_constant_p +.Nd GNU extension to determine compile time constants +.Sh SYNOPSIS +.Ft int +.Fn __builtin_constant_p "value" +.Sh DESCRIPTION +The +.Fn __builtin_constant_p +is a +.Tn GNU +extension for determining whether a value +is known to be constant at compile time. +The function is closely related to the concept of +.Dq constant folding +used by modern optimizing compilers. +.Pp +If the +.Fa value +is known to be a compile-time constant, a value 1 is returned. +If +.Fn __builtin_constant_p +returns 0, the +.Fa value +is not a compile-time constant in the sense that +.Xr gcc 1 +was unable to determine whether the value is constant or not. +.Sh EXAMPLES +A typical example of the use of +.Fn __builtin_constant_p +involves a situation where it may be desirable to +fold the computation if it involves a constant, +but a function call is needed otherwise. +For instance, +.Xr bswap16 3 +is defined in +.Nx +as: +.Bd -literal -offset indent +#define bswap16(x) \\ + (__builtin_constant_p((x)) ? \\ + __byte_swap_u16_constant(x) : __BYTE_SWAP_U16_VARIABLE(x)) +.Ed +.Sh SEE ALSO +.Xr gcc 1 , +.Xr __builtin_object_size 3 , +.Xr __builtin_return_address 3 +.Sh CAVEATS +This is a non-standard, compiler-specific extension. diff --git a/static/netbsd/man3/__builtin_prefetch.3 b/static/netbsd/man3/__builtin_prefetch.3 new file mode 100644 index 00000000..21fce7a5 --- /dev/null +++ b/static/netbsd/man3/__builtin_prefetch.3 @@ -0,0 +1,115 @@ +.\" $NetBSD: __builtin_prefetch.3,v 1.4 2024/09/07 20:33:53 rillig Exp $ +.\" +.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@iki.fi> +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 22, 2010 +.Dt __BUILTIN_PREFETCH 3 +.Os +.Sh NAME +.Nm __builtin_prefetch +.Nd GNU extension to prefetch memory +.Sh SYNOPSIS +.Ft void +.Fn __builtin_prefetch "const void *addr" "..." +.Sh DESCRIPTION +The +.Fn __builtin_prefetch +function prefetches memory from +.Fa addr . +The rationale is to minimize cache-miss latency by +trying to move data into a cache before accessing the data. +Possible use cases include frequently called sections of code +in which it is known that the data in a given address is likely +to be accessed soon. +.Pp +In addition to +.Fa addr , +there are two optional +.Xr stdarg 3 +arguments, +.Fa rw +and +.Fa locality . +The value of the latter should be a compile-time +constant integer between 0 and 3. +The higher the value, the higher the temporal locality in the data. +When +.Fa locality +is 0, it is assumed that there is little or no temporal locality in the data; +after access, it is not necessary to leave the data in the cache. +The default value is 3. +The value of +.Fa rw +is either 0 or 1, corresponding with read and write prefetch, respectively. +The default value of +.Fa rw +is 0. +Also +.Fa rw +must be a compile-time constant integer. +.Pp +The +.Fn __builtin_prefetch +function translates into prefetch instructions +only if the architecture has support for these. +If there is no support, +.Fa addr +is evaluated only if it includes side effects, +although no warnings are issued by +.Xr gcc 1 . +.Sh EXAMPLES +The following optimization appears in the heavily used +.Fn cpu_in_cksum +function that calculates checksums for the +.Xr inet 4 +headers: +.Bd -literal -offset indent +while (mlen >= 32) { + __builtin_prefetch(data + 32); + partial += *(uint16_t *)data; + partial += *(uint16_t *)(data + 2); + partial += *(uint16_t *)(data + 4); + + \&... + + partial += *(uint16_t *)(data + 28); + partial += *(uint16_t *)(data + 30); + + data += 32; + mlen -= 32; + + \&... +.Ed +.Sh SEE ALSO +.Xr gcc 1 , +.Xr attribute 3 +.Rs +.%A Ulrich Drepper +.%T What Every Programmer Should Know About Memory +.%D November 21, 2007 +.%U https://www.akkadia.org/drepper/cpumemory.pdf +.Re +.Sh CAVEATS +This is a non-standard, compiler-specific extension. diff --git a/static/netbsd/man3/__builtin_return_address.3 b/static/netbsd/man3/__builtin_return_address.3 new file mode 100644 index 00000000..ca941c00 --- /dev/null +++ b/static/netbsd/man3/__builtin_return_address.3 @@ -0,0 +1,67 @@ +.\" $NetBSD: __builtin_return_address.3,v 1.1 2010/12/19 09:30:50 jruoho Exp $ +.\" +.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@iki.fi> +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 19, 2010 +.Dt __BUILTIN_RETURN_ADDRESS 3 +.Os +.Sh NAME +.Nm __builtin_return_address +.Nd the return address of a function +.Sh SYNOPSIS +.Ft void * +.Fn __builtin_return_address "unsigned int level" +.Ft void * +.Fn __builtin_frame_address "unsigned int level" +.Sh DESCRIPTION +The +.Fn __builtin_return_address +is a +.Tn GNU +extension for obtaining the return address of the current function +or one of the callers of the current function. +.Pp +The parameter +.Fa level +specifies the number of frames that should be scanned up in the call stack. +A value 0 returns the address of the current function, +a value 1 requests the address of the caller of the current function, +a value 2 asks for the address of the caller's caller, and so forth. +If the top of the call stack has been reached, the function will return 0. +Note also that on some architectures it is only possible +to determine the address of the current function. +In such cases a value 0 is returned. +Thus, it is usually safe to only use the value 0 for +.Fa level . +.Pp +The +.Fn __builtin_frame_address +behaves similarly, but returns the address of the function +frame rather than the return address of the function. +.Sh SEE ALSO +.Xr gcc 1 , +.Xr __builtin_object_size 3 +.Sh CAVEATS +These are non-standard, compiler-specific extensions. diff --git a/static/netbsd/man3/__builtin_types_compatible_p.3 b/static/netbsd/man3/__builtin_types_compatible_p.3 new file mode 100644 index 00000000..32608d43 --- /dev/null +++ b/static/netbsd/man3/__builtin_types_compatible_p.3 @@ -0,0 +1,104 @@ +.\" $NetBSD: __builtin_types_compatible_p.3,v 1.2 2010/12/22 09:07:15 wiz Exp $ +.\" +.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@iki.fi> +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 21, 2010 +.Dt __BUILTIN_TYPES_COMPATIBLE_P 3 +.Os +.Sh NAME +.Nm __builtin_types_compatible_p +.Nd GNU extension to check equivalent types +.Sh SYNOPSIS +.Ft int +.Fn __builtin_types_compatible_p "type_a" "type_b" +.Sh DESCRIPTION +The +.Fn __builtin_types_compatible_p +is a +.Tn GNU +extension for determining whether two types are equivalent. +If +.Fa type_a +is equivalent to +.Fa type_b , +a value 1 is returned. +Otherwise +.Fn __builtin_types_compatible_p +returns 0. +.Pp +The following remarks should be taken into account. +.Bl -enum -offset indent +.It +The architecture-specific size of the two types +does not have an impact on the result. +For example, +.Fn sizeof "char *" +and +.Fn sizeof "int" +result the same value on i386, but the types naturally are not equivalent. +.It +Type qualifiers are ignored. +The function returns the same value for +.Vt long +and +.Vt const long . +.It +The amount of pointer indirection affects the result. +For example, +.Vt double * +is not equivalent to +.Vt double ** . +.It +Two types defined with +.Em typedef +are equivalent if and only if their underlying types are equivalent. +.It +The +.Em enum +type is a special case in that two +.Em enum +types are not considered equivalent. +.El +.Sh EXAMPLES +The following example combines +.Fn __builtin_types_compatible_p +and the +.Xr typeof 3 +construct: +.Bd -literal -offset indent +#define __COMPARE_TYPES(v, t) \\ + __builtin_types_compatible_p(__typeof__(v), t) + +\&... + +if (__COMPARE_TYPES(p, double) != 0) + err(EX_DATAERR, "invalid type"); +.Ed +.Sh SEE ALSO +.Xr gcc 1 , +.Xr __builtin_constant_p 3 , +.Xr typeof 3 +.Sh CAVEATS +This is a non-standard, compiler-specific extension. diff --git a/static/netbsd/man3/__insn_barrier.3 b/static/netbsd/man3/__insn_barrier.3 new file mode 100644 index 00000000..4a7f2f8a --- /dev/null +++ b/static/netbsd/man3/__insn_barrier.3 @@ -0,0 +1,63 @@ +.\" $NetBSD: __insn_barrier.3,v 1.4 2017/11/13 09:11:16 wiz Exp $ +.\" +.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@iki.fi> +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 2, 2011 +.Dt __INSN_BARRIER 3 +.Os +.Sh NAME +.Nm __insn_barrier +.Nd compiler reorder barrier +.Sh SYNOPSIS +.In sys/cdefs.h +.Ft void +.Fn __insn_barrier +.Sh DESCRIPTION +The +.Fn __insn_barrier +macro prevents GCC from moving code across the barrier. +In other words, the compiler is not allowed to reorder read and write +commands below the barrier with the code preceding the barrier. +Like with the +.Em volatile +type qualifier, +.Fn __insn_barrier +may be necessary in some corner cases to prevent the compiler +from misoptimizing. +.Sh SEE ALSO +.Xr gcc 1 , +.Xr cdefs 3 , +.Xr membar_ops 3 +.Rs +.%A Paul E. McKenney +.%T Memory Barriers: a Hardware View for Software Hackers +.%D June 7, 2010 +.%U http://www.rdrop.com/users/paulmck/scalability/paper/whymb.2010.06.07c.pdf +.Re +.Sh HISTORY +The +.Fn __insn_barrier +macro first appeared in +.Nx 2.0 . diff --git a/static/netbsd/man3/assert.3 b/static/netbsd/man3/assert.3 new file mode 100644 index 00000000..d7eb8a9b --- /dev/null +++ b/static/netbsd/man3/assert.3 @@ -0,0 +1,98 @@ +.\" $NetBSD: assert.3,v 1.14 2016/06/01 01:31:11 pgoyette Exp $ +.\" +.\" 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. +.\" +.\" @(#)assert.3 8.1 (Berkeley) 6/9/93 +.\" +.Dd June 1, 2016 +.Dt ASSERT 3 +.Os +.Sh NAME +.Nm assert +.Nd expression verification macro +.Sh SYNOPSIS +.In assert.h +.Fn assert expression +.Sh DESCRIPTION +The +.Fn assert +macro tests the given +.Ar expression +and if it is false, +the calling process is terminated. +A diagnostic message, consisting of the text of the expression, +the name of the source file, the line number and the enclosing +function, +is written to +.Em stderr +and the +.Xr abort 3 +function 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 with +the +.Xr cc 1 +option +.Fl DNDEBUG . +.Sh DIAGNOSTICS +The following diagnostic message is written to +.Em stderr +if +.Ar expression +is false: +.Bd -literal -offset indent +"assertion \e"%s\e" failed: file \e"%s\e", line %d, function \e"%s\e"\en", \e + "expression", __FILE__, __LINE__, __func__); +.Ed +.Sh SEE ALSO +.Xr cc 1 , +.Xr _DIAGASSERT 3 , +.Xr abort 3 +.Sh STANDARDS +The +.Fn assert +macro conforms to +.St -isoC-99 . +.Sh HISTORY +A +.Nm +macro appeared in +.At v7 . +.Pp +Information on the name of the enclosing function appeared in +.St -isoC-99 . diff --git a/static/netbsd/man3/attribute.3 b/static/netbsd/man3/attribute.3 new file mode 100644 index 00000000..3ac665b4 --- /dev/null +++ b/static/netbsd/man3/attribute.3 @@ -0,0 +1,392 @@ +.\" $NetBSD: attribute.3,v 1.18 2018/09/14 20:53:49 christos Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 September 14, 2018 +.Dt ATTRIBUTE 3 +.Os +.Sh NAME +.Nm attribute +.Nd non-standard compiler attribute extensions +.Sh SYNOPSIS +.In sys/cdefs.h +.Pp +.Ic __dead +.Pp +.Ic __pure +.Pp +.Ic __constfunc +.Pp +.Ic __noinline +.Pp +.Ic __unused +.Pp +.Ic __used +.Pp +.Ic __diagused +.Pp +.Ic __debugused +.Pp +.Ic __packed +.Pp +.Fn __aligned "x" +.Fn __section "section" +.Pp +.Ic __read_mostly +.Pp +.Ic __cacheline_aligned +.Pp +.Fn __predict_true "exp" +.Pp +.Fn __predict_false "exp" +.Pp +.Fn __printflike "fmtarg" "firstvararg" +.Pp +.Fn __sysloglike "fmtarg" "firstvararg" +.Sh DESCRIPTION +As an extension to the C standard, some compilers allow non-standard +attributes to be associated with functions, variables, or types, to +modify some aspect of the way the compiler treats the associated item. +The +.Tn GNU +Compiler Collection +.Pq Tn GCC , +and +.Tn LLVM/Clang , +use the +.Em __attribute__ +syntax for such attributes, +but different versions of the compilers support different attributes, +and other compilers may use entirely different syntax. +.Pp +.Nx +code should usually avoid direct use of the +.Em __attribute__ +or similar syntax provided by specific compilers. +Instead, +.Nx Ap s +.In sys/cdefs.h +header file +provides several attribute macros in a namespace +reserved for the implementation (beginning with +.Ql __ ) , +that expand to the appropriate syntax for the compiler that is in use. +.Sh ATTRIBUTES +.Bl -tag -width abc +.It Ic __dead +Certain functions, such as +.Xr abort 3 +and +.Xr exit 3 , +can never return. +When such a function is declared with +.Ic __dead , +certain optimizations are possible and warnings sensitive to the code flow graph +may be pruned. +Obviously a +.Ic __dead +function can never have return type other than +.Vt void . +.It Ic __pure +A +.Ic __pure +function is defined to be one that has no effects except +the return value, which is assumed to depend only on the +function parameters and/or global variables. +Any access to parameters and/or global variables must also be read-only. +A function that depends on volatile memory, or other comparable +system resource that can change between two consecutive calls, +can never be +.Ic __pure . +Many +.Xr math 3 +functions satisfy the definition of a +.Ic __pure +function, at least in theory. +Other examples include +.Xr strlen 3 +and +.Xr strcmp 3 . +.It Ic __constfunc +A +.Dq const function +is a stricter variant of +.Dq pure functions . +In addition to the restrictions of pure functions, a function declared with +.Ic __constfunc +can never access global variables nor take pointers as parameters. +The return value of these functions must depend +only on the passed-by-value parameters. +Note also that a function that calls non-const functions can not be +.Ic __constfunc . +The canonical example of a const function would be +.Xr abs 3 . +As with pure functions, +certain micro-optimizations are possible for functions declared with +.Ic __constfunc . +.It Ic __noinline +Sometimes it is known that inlining is undesirable or that +a function will perform incorrectly when inlined. +The +.Ic __noinline +macro expands to a function attribute that prevents +the compiler from inlining the function, irrespective +of whether the function was declared with the +.Em inline +keyword. +The attribute takes precedence over all +other compiler options related to inlining. +.It Ic __unused +Marking an unused function with the +.Ic __unused +macro inhibits warnings that a function is defined but not used. +Marking a variable with the +.Ic __unused +macro inhibits warnings that the variable is unused, +or that it is set but never read. +.It Ic __used +The +.Ic __used +macro expands to an attribute that informs the compiler +that a static variable or function is to be always retained +in the object file even if it is unreferenced. +.It Ic __diagused +The +.Ic __diagused +macro expands to an attribute that informs the compiler +that a variable or function is used only in diagnostic code, +and may be unused in non-diagnostic code. +.Pp +In the kernel, variables that are used when +.Dv DIAGNOSTIC +is defined, but unused when +.Dv DIAGNOSTIC +is not defined, may be declared with +.Ic __diagused . +In userland, variables that are used when +.Dv NDEBUG +is not defined, but unused when +.Dv NDEBUG +is defined, may be declared with +.Ic __diagused . +.Pp +Variables used only in +.Xr assert 3 +or +.Xr KASSERT 9 +macros are likely candidates for being declared with +.Ic __diagused . +.It Ic __debugused +The +.Ic __debugused +macro expands to an attribute that informs the compiler +that a variable or function is used only in debug code, +and may be unused in non-debug code. +.Pp +In either the kernel or userland, variables that are used when +.Dv DEBUG +is defined, but unused when +.Dv DEBUG +is not defined, may be declared with +.Ic __debugused . +.Pp +In the kernel, variables used only in +.Xr KDASSERT 9 +macros are likely candidates for being declared with +.Ic __debugused . +There is no established convention for the use of +.Dv DEBUG +in userland code. +.It Ic __packed +The +.Ic __packed +macro expands to an attribute that forces a variable or +structure field to have the smallest possible alignment, +potentially disregarding architecture specific alignment requirements. +The smallest possible alignment is effectively one byte +for variables and one bit for fields. +If specified on a +.Vt struct +or +.Vt union , +all variables therein are also packed. +The +.Ic __packed +macro is often useful when dealing with data that +is in a particular static format on the disk, wire, or memory. +.It Fn __aligned "x" +The +.Fn __aligned +macro expands to an attribute that specifies the minimum alignment +in bytes for a variable, structure field, or function. +In other words, the specified object should have an alignment of at least +.Fa x +bytes, as opposed to the minimum alignment requirements dictated +by the architecture and the +.Tn ABI . +Possible use cases include: +.Bl -bullet -offset indent +.It +Mixing assembly and C code. +.It +Dealing with hardware that may impose alignment requirements +greater than the architecture itself. +.It +Using instructions that may impose special alignment requirements. +Typical example would be alignment of frequently used objects along +processor cache lines. +.El +.Pp +Note that when used with functions, structures, or structure members, +.Fn __aligned +can only be used to increase the alignment. +If the macro is however used as part of a +.Vt typedef , +the alignment can both increase and decrease. +Otherwise it is only possible to decrease the alignment +for variables and fields by using the +.Ic __packed +macro. +The effectiveness of +.Fn __aligned +is largely dependent on the linker. +The +.Xr __alignof__ 3 +operator can be used to examine the alignment. +.It Fn __section "section" +The +.Fn __section +macro expands to an attribute that specifies a particular +.Fa section +to which a variable or function should be placed. +Normally the compiler places the generated objects to sections such as +.Dq data +or +.Dq text . +By using +.Fn __section , +it is possible to override this behavior, perhaps in order to place +some variables into particular sections specific to unique hardware. +.It Ic __read_mostly +The +.Ic __read_mostly +macro uses +.Fn __section +to place a variable or function into the +.Dq .data.read_mostly +section of the (kernel) +.Xr elf 5 . +The use of +.Ic __read_mostly +allows infrequently modified data to be grouped together; +it is expected that the cachelines of rarely and frequently modified +data structures are this way separated. +Candidates for +.Ic __read_mostly +include variables that are initialized once, +read very often, and seldom written to. +.It Ic __cacheline_aligned +The +.Ic __cacheline_aligned +macro behaves like +.Ic __read_mostly , +but the used section is +.Dq .data.cacheline_aligned +instead. +It also uses +.Fn __aligned +to set the minimum alignment into a predefined coherency unit. +This should ensure that frequently used data structures are +aligned on cacheline boundaries. +Both +.Ic __cacheline_aligned +and +.Ic __read_mostly +are only available for the kernel. +.It Ic __predict_true +A branch is generally defined to be a conditional execution of a +program depending on whether a certain flow control mechanism is altered. +Typical example would be a +.Dq if-then-else +sequence used in high-level languages or +a jump instruction used in machine-level code. +A branch prediction would then be defined as an +attempt to guess whether a conditional branch will be taken. +.Pp +The macros +.Fn __predict_true +and +.Fn __predict_false +annotate the likelihood of whether +a branch will evaluate to true or false. +The rationale is to improve instruction pipelining. +Semantically +.Ic __predict_true +expects that the integral expression +.Fa exp +yields nonzero. +.It Ic __predict_false +The +.Ic __predict_false +expands to an attribute that instructs the compiler +to predict that a given branch will be likely false. +As programmers are notoriously bad at predicting +the likely behavior of their code, profiling and +empirical evidence should precede the use of +.Ic __predict_false +and +.Ic __predict_true . +.It Fn __printflike "fmtarg" "firstvararg" +Marks a function as taking printf-like arguments. +.Fa fmtarg +is the index of the format string in the argument list, and +.Fa firstvararg +is the index of the first item of the vararg list. +.It Fn __sysloglike "fmtarg" "firstvararg" +Marks a function as taking syslog-like arguments. +Allows use of the %m formatting code. +.Fa fmtarg +is the index of the format string in the argument list, and +.Fa firstvararg +is the index of the first item of the vararg list, or +.Dv 0 +if the argument is a +.Ft va_list . +.El +.Sh SEE ALSO +.Xr clang 1 , +.Xr gcc 1 , +.Xr __builtin_object_size 3 , +.Xr cdefs 3 , +.Xr c 7 +.Sh CAVEATS +It goes without saying that portable applications +should steer clear from non-standard extensions specific +to any given compiler. +Even when portability is not a concern, +use these macros sparsely and wisely. diff --git a/static/netbsd/man3/bitmap.3 b/static/netbsd/man3/bitmap.3 new file mode 100644 index 00000000..f6c89d85 --- /dev/null +++ b/static/netbsd/man3/bitmap.3 @@ -0,0 +1,151 @@ +.\" $NetBSD: bitmap.3,v 1.12 2018/03/08 06:47:30 wiz Exp $ +.\" +.\" Copyright (c) 2012 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 8, 2018 +.Dt BITMAP 3 +.Os +.Sh NAME +.Nm __BITMAP_CLR , +.Nm __BITMAP_ISSET , +.Nm __BITMAP_SET , +.Nm __BITMAP_SIZE , +.Nm __BITMAP_TYPE , +.Nm __BITMAP_ZERO +.Nd bitmap manipulation macros +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/bitops.h +.Fn __BITMAP_CLR "int bit" "type *bitmap" +.Fn __BITMAP_ISSET "int bit" "type *bitmap" +.Fn __BITMAP_SET "int bit" "type *bitmap" +.Fn __BITMAP_SIZE "type" "int nbits" +.Fn __BITMAP_TYPE "name" "type" "int nbits" +.Fn __BITMAP_ZERO "type *bitmap" +.Sh DESCRIPTION +The supplied macros are similar to the +.Xr select 2 +.Fn FD_SET +family, to the +.Xr setbit 9 , +macros and the +.Xr bitstring 3 +library. +They are different from +.Fn FD_SET +because they are designed to handle multiple sized bitmaps at the same time, +and they can be of any integral type. +They are different from +.Xr setbit 9 +because they can operate on different integral types, not just on bytes. +They are different from +.Xr bitstring 3 +because they are just macros, they don't allocate memory or use code, +and they can be used in both kernel and userland. +.Pp +The following macros are provided for manipulating creating and manipulating +bitmaps: +.Pp +.Fn __BITMAP_CLR bit bitmap +removes the given +.Fa bit +from the +.Fa bitmap . +.Pp +.Fn __BITMAP_ISSET bit bitmap +is non-zero if +.Fa bit +is a member of +.Fa bitmap , +zero otherwise. +.Pp +.Fn __BITMAP_SET bit bitmap +Sets the given +.Fa bit +in the +.Fa bitmap . +.Pp +.Fn __BITMAP_SIZE type nbits +Returns the number of elements would be required of the given +.Fa type +to hold +.Fa nbits . +.Pp +.Fn __BITMAP_TYPE name type nbits +Declares the properly sized bitmap structure +of the given +.Fa type +that holds +.Fa nbits +and is named +.Fa name . +.Pp +.Fn __BITMAP_ZERO bitmap +initializes a descriptor set pointed to by +.Fa bitmap +to the null set. +.Pp +The behavior of these macros is undefined for negative +bit values or ones greater than the number of bits the bitmap can hold. +.Sh EXAMPLES +.Bd -literal +#include <sys/bitops.h> + +int +main(int argc, char **argv) +{ + __BITMAP_TYPE(, uint32_t, 5000) bitmap; + + /* Initialize the read set to null */ + __BITMAP_ZERO(&bitmap); + + /* Set bit 1 */ + __BITMAP_SET(1, &bitmap); + + for (size_t i = 0; i < 5000; i++) { + if (__BITMAP_ISSET(i, &bitmap)) { + /* Should just print 1 */ + printf("Bit %zu is set\en", i); + __BITMAP_CLR(i, &bitmap); + } + break; + } + return 0; +} +.Ed +.Sh SEE ALSO +.Xr select 2 , +.Xr bitops 3 , +.Xr bitstring 3 , +.Xr setbit 9 +.Sh HISTORY +The +.Fn __BITMAP_* +macros appeared in +.Nx 7.0 . diff --git a/static/netbsd/man3/bitops.3 b/static/netbsd/man3/bitops.3 new file mode 100644 index 00000000..ae3bd06a --- /dev/null +++ b/static/netbsd/man3/bitops.3 @@ -0,0 +1,64 @@ +.\" $NetBSD: bitops.3,v 1.6 2020/01/13 16:11:53 uwe Exp $ +.\" +.\" Copyright (c) 2011 Jukka Ruohonen <jruohonen@iki.fi> +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 4, 2012 +.Dt BITOPS 3 +.Os +.Sh NAME +.Nm bitops +.Nd functions related to bits and integers +.Sh SYNOPSIS +.In sys/bitops.h +.Sh DESCRIPTION +The +.In sys/bitops.h +header provides macros and +.Vt static inline +functions related to bits and integers. +Among these are: +.Bl -tag -width ".Xr fast_divide32 3" -offset indent +.It Xr bitmap 3 +bitmap manipulation macros +.It Xr fast_divide32 3 +a function for fast 32-bit division +.It Xr ffs32 3 +functions to find the first and last set bit in integers of type +.Vt uint32_t +and +.Vt uint64_t +.It Xr ilog2 3 +a macro for binary logarithm +.El +.Sh SEE ALSO +.Xr bits 3 , +.Xr bitstring 3 , +.Xr cdefs 3 , +.Xr param 3 +.Sh HISTORY +The +.In sys/bitops.h +header first appeared in +.Nx 4.0 . diff --git a/static/netbsd/man3/bits.3 b/static/netbsd/man3/bits.3 new file mode 100644 index 00000000..9110c11c --- /dev/null +++ b/static/netbsd/man3/bits.3 @@ -0,0 +1,160 @@ +.\" $NetBSD: bits.3,v 1.22 2022/01/22 09:22:41 wiz Exp $ +.\" +.\" Copyright (c) 2006, 2010 David Young. 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 DAVID YOUNG ``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 DAVID +.\" YOUNG 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, 2022 +.Dt BITS 3 +.Os +.Sh NAME +.Nm __BIT , +.Nm __BITS , +.Nm __MASK , +.Nm __SHIFTIN , +.Nm __SHIFTOUT , +.Nm __SHIFTOUT_MASK +.Nd "macros for preparing bitmasks and operating on bit fields" +.Sh SYNOPSIS +.In sys/param.h +.In sys/cdefs.h +.Ft uintmax_t +.Fn __BIT "n" +.Ft uintmax_t +.Fn __BITS "m" "n" +.Ft uintmax_t +.Fn __MASK "n" +.Ft uintmax_t +.Fn __SHIFTIN "v" "mask" +.Ft uintmax_t +.Fn __SHIFTOUT "v" "mask" +.Ft uintmax_t +.Fn __SHIFTOUT_MASK "mask" +.Sh DESCRIPTION +These macros prepare bitmasks, extract bitfields from words, and +insert bitfields into words. +A +.Dq bitfield +is a span of consecutive bits defined by a bitmask, where 1s select +the bits in the bitfield. +.Pp +Use +.Fn __BIT , +.Fn __BITS , +and +.Fn __MASK +to define bitmasks: +.Bl -tag -width __BITS -offset indent +.It Fn __BIT "n" +Return a bitmask with bit +.Fa n +set, where the least significant bit is bit 0. +.It Fn __BITS "m" "n" +Return a bitmask with bits +.Fa m +through +.Fa n , +inclusive, set. +It does not matter whether +.Fa m No > Fa n +or +.Fa m No <= Fa n . +The least significant bit is bit 0. +.It Fn __MASK "n" +Return a bitmask with the first +.Fa n +bits set. +That is, bits 0 through +.Fa n +- 1, inclusive, set. +.El +.Pp +.Fn __SHIFTIN , +.Fn __SHIFTOUT , +and +.Fn __SHIFTOUT_MASK +help read and write bitfields from words: +.Bl -tag -width __SHIFTOUT_MASK -offset indent +.It Fn __SHIFTIN "v" "mask" +Left-shift bits +.Fa v +into the bitfield defined by +.Fa mask , +and return them. +No side-effects. +.It Fn __SHIFTOUT "v" "mask" +Extract and return the bitfield selected by +.Fa mask +from +.Fa v , +right-shifting the bits so that the rightmost selected bit is at +bit 0. +No side-effects. +.It Fn __SHIFTOUT_MASK "mask" +Right-shift the bits in +.Fa mask +so that the rightmost non-zero bit is at bit 0. +This is useful for finding the greatest unsigned value that a +bitfield can hold. +No side-effects. +Note that +.Fn __SHIFTOUT_MASK "m" += +.Fn __SHIFTOUT "m" "m" . +.El +.Sh EXAMPLES +The following example demonstrates basic usage of the +.Nm bits +macros: +.Bd -literal -offset indent +uint32_t bits, mask, val; + +bits = __BITS(2, 3); /* 00001100 */ +mask = __BIT(2) | __BIT(3); /* 00001100 */ + +val = __SHIFTIN(0x03, mask); /* 00001100 */ +val = __SHIFTOUT(0xf, mask); /* 00000011 */ +.Ed +.Sh SEE ALSO +.Xr bitops 3 , +.Xr cdefs 3 +.Sh HISTORY +The +.Nm bits +macros first appeared in +.Xr atw 4 , +with different names and implementation. +In their current form these macros appeared in +.Nx 4.0 . +.Sh AUTHORS +The +.Nm bits +macros were written by +.An David Young Aq Mt dyoung@NetBSD.org . +.An Matt Thomas Aq Mt matt@NetBSD.org +suggested important improvements to the implementation, and +contributed the macro names +.Fn SHIFTIN +and +.Fn SHIFTOUT . diff --git a/static/netbsd/man3/bitstring.3 b/static/netbsd/man3/bitstring.3 new file mode 100644 index 00000000..cda7e437 --- /dev/null +++ b/static/netbsd/man3/bitstring.3 @@ -0,0 +1,184 @@ +.\" $NetBSD: bitstring.3,v 1.18 2017/07/03 21:30:58 wiz Exp $ +.\" +.\" 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. +.\" +.\" @(#)bitstring.3 8.1 (Berkeley) 7/19/93 +.\" +.Dd December 29, 2016 +.Dt BITSTRING 3 +.Os +.Sh NAME +.Nm bit_alloc , +.Nm bit_clear , +.Nm bit_decl , +.Nm bit_ffc , +.Nm bit_ffs , +.Nm bit_nclear , +.Nm bit_nset , +.Nm bit_set , +.Nm bitstr_size , +.Nm bit_test +.Nd bit-string manipulation macros +.Sh SYNOPSIS +.In sys/types.h +.In bitstring.h +.Ft bitstr_t * +.Fn bit_decl "bitstr_t *name" "size_t nbits" +.Ft bitstr_t * +.Fn bit_alloc "size_t nbits" +.Fn bit_clear "bitstr_t *name" "size_t bit" +.Fn bit_ffc "const bitstr_t *name" "size_t nbits" "int *value" +.Fn bit_ffs "const bitstr_t *name" "size_t nbits" "int *value" +.Fn bit_nclear "bitstr_t *name" "size_t start" "size_t stop" +.Fn bit_nset "bitstr_t *name" "size_t start" "size_t stop" +.Fn bit_set "bitstr_t *name" "size_t bit" +.Fn bitstr_size "size_t nbits" +.Fn bit_test "const bitstr_t *name" "size_t bit" +.Sh DESCRIPTION +These macros operate on strings of bits. +.Pp +The macro +.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. +.Pp +The macro +.Fn bit_decl +allocates sufficient space to store +.Fa nbits +bits on the stack. +.Pp +The macro +.Fn bitstr_size +returns the number of elements of type +.Fa bitstr_t +necessary to store +.Fa nbits +bits. +This is useful for copying bit strings. +.Pp +The macros +.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 +macros +set or clear the zero-based numbered bits from +.Fa start +to +.Fa stop +in the bit string +.Ar name . +.Pp +The +.Fn bit_test +macro +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_ffs +macro +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 macro +.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 arguments to these 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 + +void +make_lpr_available(void) +{ + 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 bitmap 3 , +.Xr calloc 3 , +.Xr setbit 9 +.Sh HISTORY +The +.Nm bitstring +functions first appeared in +.Bx 4.4 . diff --git a/static/netbsd/man3/cdefs.3 b/static/netbsd/man3/cdefs.3 new file mode 100644 index 00000000..25cc5f8b --- /dev/null +++ b/static/netbsd/man3/cdefs.3 @@ -0,0 +1,116 @@ +.\" $NetBSD: cdefs.3,v 1.5 2019/11/10 18:45:09 christos Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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, 2019 +.Dt CDEFS 3 +.Os +.Sh NAME +.Nm cdefs +.Nd common definitions and macros +.Sh SYNOPSIS +.In sys/cdefs.h +.Sh DESCRIPTION +The +.In sys/cdefs.h +header includes some common definitions and macros +typical to the C language conventions of +.Nx . +Among these are: +.Bl -bullet -offset indent +.It +Certain C language properties and definitions that +are versioned according to the support in compilers. +Examples include the +.Em __func__ +keyword and the +.Em restrict +type qualifier from +.Tn C99 . +.It +Macros and definitions specific to compilers, preprocessors, and linkers; see +.Xr __BIT 3 , +.Xr __BITS 3 , +.Xr __CONCAT 3 , +.Xr __FPTRCAST 3 , +.Xr __SHIFTIN 3 , +.Xr __SHIFTOUT 3 , +.Xr __SHIFTOUT_MASK 3 , +.Xr __UNCONST 3 , +.Xr __UNVOLATILE 3 , +.Xr __USE 3 , +.Xr __insn_barrier 3 , +and +.Xr attribute 3 . +.It +Utility macros provided for convenience; see +.Xr __arraycount 3 +and +.Xr bits 3 . +.El +.Pp +The header also contains the +.Fn __RCSID +and +.Fn __KERNEL_RCSID +macros used for version control system +.Pq Tn VCS +identifiers. +Thus, all +.Nx +source code files typically include +.In sys/cdefs.h , +included as the first thing right after any possible copyright texts; +.Bd -literal -offset indent +/*- + * Copyright (c) 1984 John Doe + * All rights reserved. + * + * Redistribution and use in source and binary forms, + * with or without modification, are permitted. + */ + +#include <sys/cdefs.h> +__RCSID("$NetBSD: cdefs.3,v 1.5 2019/11/10 18:45:09 christos Exp $"); +.Ed +.Pp +It is possible to identify the +.Tn RCS +keyword strings by using +.Xr ident 1 . +.Sh SEE ALSO +.Xr ident 1 , +.Xr param 3 , +.Xr stddef 3 , +.Xr types 3 , +.Xr c 7 +.Sh HISTORY +The +.In sys/cdefs.h +header was originally imported from +.Bx 386 . diff --git a/static/netbsd/man3/container_of.3 b/static/netbsd/man3/container_of.3 new file mode 100644 index 00000000..0933753e --- /dev/null +++ b/static/netbsd/man3/container_of.3 @@ -0,0 +1,78 @@ +.\" $NetBSD: container_of.3,v 1.2 2024/10/09 00:55:24 uwe Exp $ +.\" +.\" Copyright (c) 2024 The NetBSD Foundation, 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. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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 8, 2011 +.Dt CONTAINER_OF 3 +.Os +.Sh NAME +.Nm container_of +.Nd cast a pointer to member of a structure to a pointer of its +container structure. +.Sh SYNOPSIS +.In sys/container_of.h +.Ft "type *" +.Fn container_of "pointer" "type" "member" +.Sh DESCRIPTION +Given a +.Fa pointer +that points to a +.Fa member +of the container structure +.Fa type +the +.Fn container_of +macro returns a pointer that points to the enclosing container structure. +.Pp +A compiler error will result if +.Ar member +is not aligned to a byte boundary +.Pq i.e. it is a bit-field . +.Sh EXAMPLES +.Bd -literal +#include <assert.h> +#include <sys/container_of.h> +struct container { + double other_member; + int member; +}; + +struct container one; + +void test(void) { + int *ptr = &one.member; + struct container *onep = container_of(ptr, struct container, member); + assert(onep == &one); +} +.Ed +.Sh SEE ALSO +.Xr __alignof__ 3 , +.Xr offsetof 3 , +.Xr stddef 3 , +.Xr typeof 3 +.Sh HISTORY +The +.Fn container_of +macro appeared first in the Linux kernel. diff --git a/static/netbsd/man3/dirent.3 b/static/netbsd/man3/dirent.3 new file mode 100644 index 00000000..5efa9126 --- /dev/null +++ b/static/netbsd/man3/dirent.3 @@ -0,0 +1,214 @@ +.\" $NetBSD: dirent.3,v 1.7 2021/08/12 20:25:26 andvar Exp $ +.\" +.\" Copyright (c) 1983, 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. +.\" +.\" @(#)dir.5 8.3 (Berkeley) 4/19/94 +.\" +.Dd September 7, 2019 +.Dt DIRENT 3 +.Os +.Sh NAME +.Nm dirent +.Nd directory format +.Sh SYNOPSIS +.In sys/types.h +.In sys/dirent.h +.Ft mode +.Fn DTTOIF "dirtype" +.Ft dirtype +.Fn IFTODT "mode" +.Sh DESCRIPTION +Directories provide a convenient hierarchical method of grouping +files while obscuring the underlying details of the storage medium. +A directory file is differentiated from a plain file +by a flag in its +.Xr inode 5 +entry. +It consists of records (directory entries) each of which contains +information about a file and a pointer to the file itself. +Directory entries may contain other directories +as well as plain files; such nested directories are referred to as +subdirectories. +A hierarchy of directories and files is formed in this manner +and is called a file system (or referred to as a file system tree). +.\" An entry in this tree, +.\" nested or not nested, +.\" is a pathname. +.Pp +Each directory file contains two special directory entries; one is a pointer +to the directory itself +called dot +.Ql \&. +and the other a pointer to its parent directory called dot-dot +.Ql \&.. . +Dot and dot-dot +are valid pathnames, however, +the system root directory +.Ql / , +has no parent and dot-dot points to itself like dot. +.Pp +File system nodes are ordinary directory files on which has +been grafted a file system object, such as a physical disk or a +partitioned area of such a disk. +(See +.Xr mount 8 . ) +.Sh IMPLEMENTATION NOTES +The directory entry format is defined in the file +.In sys/dirent.h , +which is also included by +.In dirent.h . +The format is represented by the +.Em dirent +structure, which contains the following entries: +.Bd -literal -offset indent +ino_t d_fileno; +uint16_t d_reclen; +uint16_t d_namlen; +uint8_t d_type; +char d_name[MAXNAMLEN + 1]; +.Ed +.Pp +These are: +.Bl -enum -offset indent +.It +The +.Fa d_fileno +entry is a number which is unique for each +distinct file in the filesystem. +Files that are linked by hard links (see +.Xr link 2 ) +have the same +.Fa d_fileno . +If +.Fa d_fileno +is zero, the entry refers to a deleted file. +The type +.Va ino_t +is defined in +.In sys/types.h . +.It +The +.Fa d_reclen +entry is the length, in bytes, of the directory record. +.It +The +.Fa d_namlen +entry specifies the length of the file name excluding the NUL. +Thus the actual size of +.Fa d_name +may vary from 1 to +.Dv MAXNAMLEN +\&+ 1. +.It +The +.Fa d_type +is the type of the file. +.It +The +.Fa d_name +entry contains a NUL-terminated file name. +.El +.Pp +The following table lists the types available for +.Vt d_type +and the corresponding ones used in the +.Em struct stat +(see +.Xr stat 2 ) , +respectively: +.Pp +.Bl -column -offset indent -compact \ +"DT_UNKNOWN " "DT_UNKNOWN " "DT_UNKNOWN " +.It Sy Dirent Ta Sy Stat Ta Sy Description +.It Dv DT_UNKNOWN Ta - Ta unknown file type +.It Dv DT_FIFO Ta Dv S_IFIFO Ta named pipe +.It Dv DT_CHR Ta Dv S_IFCHR Ta character device +.It Dv DT_DIR Ta Dv S_IFDIR Ta directory +.It Dv DT_BLK Ta Dv S_IFBLK Ta block device +.It Dv DT_REG Ta Dv S_IFREG Ta regular file +.It Dv DT_LNK Ta Dv S_IFLNK Ta symbolic link +.It Dv DT_SOCK Ta Dv S_IFSOCK Ta UNIX domain socket +.It Dv DT_WHT Ta Dv S_IFWHT Ta dummy Dq whiteout inode +.El +.Pp +The +.Dv DT_WHT +type is internal to the implementation and +should not be seen in normal user applications. +The macros +.Fn DTTOIF +and +.Fn IFTODT +can be used to convert from +.Em struct dirent +types to +.Em struct stat +types, and vice versa. +.Sh COMPATIBILITY +The +.St -p1003.1-2001 +standard specifies only the fields +.Va d_ino +and +.Va d_name . +The remaining fields are available on many, but not all systems. +.Pp +Furthermore, the standard leaves the size of +.Va d_name +as unspecified, mentioning only that the number of +bytes preceding the terminating NUL shall not exceed +.Dv NAME_MAX . +Because of this, and because the +.Va d_namlen +field may not be present, a portable application should determine the size of +.Va d_name +by using +.Xr strlen 3 +instead of applying the +.Fn sizeof +operator. +.Sh SEE ALSO +.Xr getdents 2 , +.Xr fs 5 , +.Xr inode 5 +.\" .Sh STANDARDS +.\" +.\" XXX: Conformance is unclear, cf. PR lib/43310. +.\" +.\" Given the noted limitations, the +.\".In dirent.h +.\" header conforms to +.\" .St -p1003.1-2001 . +.Sh HISTORY +A +directory file format appeared in +.At v1 . +The +.Em dirent +structure appeared in +.Bx 4.3 reno . diff --git a/static/netbsd/man3/dl_iterate_phdr.3 b/static/netbsd/man3/dl_iterate_phdr.3 new file mode 100644 index 00000000..d115e986 --- /dev/null +++ b/static/netbsd/man3/dl_iterate_phdr.3 @@ -0,0 +1,84 @@ +.\" $NetBSD: dl_iterate_phdr.3,v 1.2 2010/10/16 12:05:48 wiz Exp $ +.\" $OpenBSD: dl_iterate_phdr.3,v 1.3 2007/05/31 19:19:48 jmc Exp $ +.\" +.\" Copyright (c) 2005 Mark Kettenis +.\" +.\" 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 October 16, 2010 +.Dt DL_ITERATE_PHDR 3 +.Os +.Sh NAME +.Nm dl_iterate_phdr +.Nd iterate over program headers +.Sh SYNOPSIS +.In link.h +.Ft int +.Fn dl_iterate_phdr "int (*callback)(struct dl_phdr_info *, size_t, void*)" "void *data" +.Sh DESCRIPTION +The +.Fn dl_iterate_phdr +function iterates over all shared objects loaded into a process's +address space, calling +.Fa callback +for each shared object, passing it information about the object's +program headers and the +.Fa data +argument. +The information about the program headers is passed in a structure +that is defined as: +.Bd -literal +struct dl_phdr_info { + Elf_Addr dlpi_addr; + const char *dlpi_name; + const Elf_Phdr *dlpi_phdr; + Elf_Half dlpi_phnum; + unsigned long long int dlpi_adds; + unsigned long long int dlpi_subs; + size_t dlpi_tls_modid; + void *dlpi_tls_data; +}; +.Ed +.Pp +The members of +.Li struct dl_phdr_info +have the following meaning: +.Bl -tag -width XXXdlpi_phdr +.It Fa dlpi_addr +The base address at which the shared object is mapped into the address +space of the calling process. +.It Fa dlpi_name +The name of the shared object. +.It Fa dlpi_phdr +A pointer to the shared object's program headers. +.It Fa dlpi_phnum +The number of program headers in the shared object. +.It Fa dlpi_adds +The number of objects added into the main program. +.It Fa dlpi_subs +The number of objects removed from the main program. +.El +.Pp +To make it possible for programs to check whether any new members have +been added, the size of the structure is passed as an argument to +.Fa callback . +.Sh SEE ALSO +.Xr ld 1 , +.Xr ld.elf_so 1 , +.Xr dlfcn 3 , +.Xr elf 5 +.Sh HISTORY +The +.Nm +function first appeared in +.Nx 6.0 . diff --git a/static/netbsd/man3/dlfcn.3 b/static/netbsd/man3/dlfcn.3 new file mode 100644 index 00000000..65910c07 --- /dev/null +++ b/static/netbsd/man3/dlfcn.3 @@ -0,0 +1,377 @@ +.\" $NetBSD: dlfcn.3,v 1.42 2024/03/09 18:43:39 gutteridge Exp $ +.\" +.\" Copyright (c) 1998 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Paul Kranenburg. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 7, 2024 +.Dt DLFCN 3 +.Os +.Sh NAME +.Nm _dlauxinfo , +.Nm dlopen , +.Nm dlclose , +.Nm dlsym , +.Nm dlvsym , +.Nm dladdr , +.Nm dlctl , +.Nm dlerror +.Nd dynamic link interface +.Sh LIBRARY +(These functions are not in a library. +They are included in every +dynamically linked program automatically.) +.Sh SYNOPSIS +.In dlfcn.h +.Ft "void *" +.Fn _dlauxinfo "void" +.Ft "void *" +.Fn dlopen "const char *path" "int mode" +.Ft "int" +.Fn dlclose "void *handle" +.Ft "void *" +.Fn dlsym "void * restrict handle" "const char * restrict symbol" +.Ft "void *" +.Fn dlvsym "void * restrict handle" "const char * restrict symbol" "const char *version" +.Ft "int" +.Fn dladdr "void * restrict addr" "Dl_info * restrict dli" +.Ft "int" +.Fn dlctl "void *handle" "int cmd" "void *data" +.Ft "char *" +.Fn dlerror "void" +.Sh DESCRIPTION +These functions provide an interface to the run-time linker +.Xr ld.so 1 . +They allow new shared objects to be loaded into the process' address space +under program control. +.Pp +The +.Fn _dlauxinfo +function returns a pointer to the +.Xr elf 5 +array of +.Vt AuxInfo +structures for the current executable. +.Pp +The +.Fn dlopen +function takes the name of a shared object as the first argument. +The +.Fa path +argument can be specified as either an absolute pathname to a shared object +or just the name of the shared object itself. +When an absolute pathname is specified, +only the path provided will be searched. +When just a shared object name is specified, the same search rules apply that +are used for +.Dq intrinsic +shared object searches +.Po +see +.Xr ld.elf_so 1 +.Pc . +.Pp +Shared libraries take the following form: +.Sm off +.Ic lib\^ Ao Ar name Ac Ic .so Oo Ic \&. Ar xx\^ Oo Ic \&. Ar yy\^ Oc Oc . +.Sm on +.Pp +The shared object is mapped into the address space, relocated, and +its external references are resolved in the same way as is done +with the implicitly loaded shared libraries at program startup. +.Pp +If the first argument is +.Dv NULL , +.Fn dlopen +returns a +.Fa handle +on the global symbol object. +This object +provides access to all symbols from an ordered set of objects consisting +of the original program image and any dependencies loaded during startup. +.Pp +The +.Fa mode +parameter specifies symbol resolution time and symbol visibility. +One of the following values may be used to specify symbol resolution time: +.Bl -tag -width ".Dv RTLD_NODELETE" -offset indent +.It Dv RTLD_NOW +Symbols are resolved immediately. +.It Dv RTLD_LAZY +Symbols are resolved when they are first referred to. +This is the default value if resolution time is unspecified. +.El +.Pp +One of the following values may be used to specify symbol visibility: +.Bl -tag -width ".Dv RTLD_NODELETE" -offset indent +.It Dv RTLD_GLOBAL +The object's symbols and the symbols of its dependencies will be visible to +other objects. +.It Dv RTLD_LOCAL +The object's symbols and the symbols of its dependencies will not be visible to +other objects. +This is the default value if visibility is unspecified. +.El +.Pp +To specify both resolution time and visibility, bitwise inclusive +.Tn OR +one of each of the above values together. +If an object was opened with +.Dv RTLD_LOCAL +and later opened with +.Dv RTLD_GLOBAL , +then it is promoted to +.Dv RTLD_GLOBAL . +.Pp +Additionally, one of the following flags may be +.Tn OR Ap ed +into the +.Fa mode +argument: +.Bl -tag -width ".Dv RTLD_NODELETE" -offset indent +.It Dv RTLD_NODELETE +Prevents unload of the loaded object on +.Fn dlclose . +The same behaviour may be requested by +.Fl z Cm nodelete +option of the static linker +.Xr ld 1 . +.It Dv RTLD_NOLOAD +Only return valid handle for the object if it is already loaded in +the process address space, otherwise do not load the object and return +.Dv NULL . +.El +.Pp +.Fn dlopen +returns a +.Fa handle +to be used in calls to +.Fn dlclose , +.Fn dlsym , +.Fn dlvsym , +and +.Fn dlctl . +If the named shared object has already +been loaded by a previous call to +.Fn dlopen +.Pq and not yet unloaded by Fn dlclose , +a +.Fa handle +referring to the resident copy is returned. +.Pp +.Fn dlclose +unlinks and removes the object referred to by +.Fa handle +from the process address space. +If multiple calls to +.Fn dlopen +have been done on this object, or the object was one loaded at startup time, +or the object is a dependency of another object +then the object is removed when its reference count drops to zero. +.Fn dlclose +returns 0 on success and non-zero on failure. +.Pp +.Fn dlsym +looks for a definition of +.Fa symbol +in the shared object designated by +.Fa handle , +and all shared objects that are listed as dependencies. +The symbol's address is returned. +If the symbol cannot be resolved, +.Dv NULL +is returned. +.Pp +.Fn dlsym +may also be called with special +.Fa handle +values. +.Fn dlsym +respects symbol visibility as specified by the +.Fn dlopen +.Fa mode +parameter. +However, the symbols of an object's dependencies are always visible to it. +All shared objects loaded at program startup are globally visible. +Only the symbols in the main executable that are referenced by a +shared object at link time will be visible unless it has been linked +with the +.Fl Fl export-dynamic +option where all of its symbols will be visible. +The following special +.Fa handle +values may be used with +.Fn dlsym : +.Bl -tag -width ".Dv RTLD_DEFAULT" -offset indent +.It Dv NULL +Interpreted as a reference to the executable or shared object +from which the call is being made. +Thus an object can reference its own symbols and the symbols of its +dependencies without calling +.Fn dlopen . +.It Dv RTLD_DEFAULT +All the visible shared objects and the executable will be searched in the order +they were loaded. +.It Dv RTLD_NEXT +The search for +.Fa symbol +is limited to the visible shared objects which were loaded after the one +issuing the call to +.Fn dlsym . +Thus, if +.Fn dlsym +is called from the main program, all the visible shared libraries are searched. +If it is called from a shared library, all subsequently visible shared +libraries are searched. +.It Dv RTLD_SELF +The search for +.Fa symbol +is limited to the shared object issuing the call to +.Fn dlsym +and those shared objects which were loaded after it that are visible. +.El +.Pp +.Fn dlvsym +does the same as +.Fn dlsym +but takes a +.Fa version +string as an additional argument. +Both the +.Fa symbol +and the +.Fa version +must match in order for the symbol to be resolved. +.Pp +.Fn dladdr +examines all currently mapped shared objects for a symbol whose address \(em +as mapped in the process address space \(em is closest to but not exceeding +the value passed in the first argument +.Fa addr . +The symbols of a shared object are only eligible if +.Fa addr +is between the base address of the shared object and the value of the +symbol +.Va _end +in the same shared object. +If no object for which this condition holds true can be found, +.Fn dladdr +will return 0. +Otherwise, a non-zero value is returned and the +.Fa dli +argument will be used to provide information on the selected symbol +and the shared object it is contained in. +The +.Fa dli +argument points at a caller-provided +.Vt Dl_info +structure defined as follows: +.Bd -literal -offset indent +typedef struct { + const char *dli_fname; /* File defining the symbol */ + void *dli_fbase; /* Base address */ + const char *dli_sname; /* Symbol name */ + const void *dli_saddr; /* Symbol address */ +} Dl_info; +.Ed +.Pp +The structure members are further described as follows: +.Bl -tag -width Fa +.It Fa dli_fname +The pathname of the shared object containing the address +.Fa addr . +.It Fa dli_fbase +The base address at which this shared object is loaded in the process +address space. +This may be zero if the symbol was found in the internally generated +.Dq copy +section +.Po +see +.Xr link 5 +.Pc +which is not associated with a file. +.It Fa dli_sname +points at the nul-terminated name of the selected symbol +.It Fa dli_saddr +is the actual address +.Pq as it appears in the process address space +of the symbol. +.El +.Pp +.Em Note : +both strings pointed at by +.Fa dli_fname +and +.Fa dli_sname +reside in memory private to the run-time linker module and should not +be modified by the caller. +.Pp +In dynamically linked programs, the address of a global function will +point to its program linkage table entry, rather than to the entry +point of the function itself. +This causes most global functions to appear to be defined within the +main executable, rather than in the shared libraries where the actual +code resides. +.Pp +.Fn dlctl +provides an interface similar to +.Xr ioctl 2 +to control several aspects of the run-time linker's operation. +This interface is +.Ud +.Pp +.Fn dlerror +returns a character string representing the most recent error that has +occurred while processing one of the other functions described here. +If no dynamic linking errors have occurred since the last invocation of +.Fn dlerror , +.Fn dlerror +returns +.Dv NULL . +Thus, invoking +.Fn dlerror +a second time, immediately following a prior invocation, will result in +.Dv NULL +being returned. +.Sh ERRORS +.Bl -diag +.It Cannot dlopen non-loadable /usr/lib/libpthread.so.1 +A program tries to +.Fn dlopen +a module that needs +.Lb libpthread +but the program isn't linked against it itself. +.El +.Sh SEE ALSO +.Xr ld 1 , +.Xr rtld 1 , +.Xr dlinfo 3 , +.Xr link 5 +.Sh HISTORY +Some of the +.Nm dl* +functions first appeared in SunOS\~4. diff --git a/static/netbsd/man3/dlinfo.3 b/static/netbsd/man3/dlinfo.3 new file mode 100644 index 00000000..709c00f3 --- /dev/null +++ b/static/netbsd/man3/dlinfo.3 @@ -0,0 +1,285 @@ +.\" $NetBSD: dlinfo.3,v 1.7 2022/03/06 23:36:01 andvar Exp $ +.\" +.\" Copyright (c) 2003 Alexey Zelkin <phantom@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: head/lib/libc/gen/dlinfo.3 267774 2014-06-23 08:25:03Z bapt $ +.\" +.Dd January 13, 2020 +.Dt DLINFO 3 +.Os +.Sh NAME +.Nm dlinfo +.Nd information about a dynamically loaded object +.Sh LIBRARY +(These functions are not in a library. +They are included in every +dynamically linked program automatically.) +.Sh SYNOPSIS +.In link.h +.In dlfcn.h +.Ft int +.Fn dlinfo "void *handle" "int request" "void *p" +.Sh DESCRIPTION +The +.Fn dlinfo +function provides information about a dynamically loaded object. +The action taken by +.Fn dlinfo +and exact meaning and type of +.Fa p +argument depend on value of the +.Fa request +argument provided by caller. +.Pp +The +.Fa handle +argument is either the value returned from the +.Xr dlopen 3 +function call or special handle +.Dv RTLD_SELF . +If +.Fa handle +is the value returned from +.Xr dlopen 3 , +the information returned by the +.Fn dlinfo +function pertains to the specified object. +If +.Fa handle +is the special handle +.Dv RTLD_SELF , +the information returned pertains to the caller itself. +.Pp +Possible values for the +.Fa request +argument are: +.Bl -tag -width "Dv RTLD_" +.It Dv RTLD_DI_LINKMAP +Retrieve the pointer to the +.Vt Link_map +for the specified +.Fa handle . +On successful return, the +.Fa p +argument is filled with the pointer to the +.Vt Link_map +structure +.Pq Fa "Link_map **p" +describing a shared object specified by the +.Fa handle +argument. +The +.Vt Link_map +structures are maintained as a doubly linked list by +.Xr ld.so 1 , +in the same order as +.Xr dlopen 3 +and +.Xr dlclose 3 +are called. +.Pp +The +.Vt Link_map +structure is defined in +.In link.h +and has the following members: +.Bd -literal -offset indent +caddr_t l_addr; /* Base Address of library */ +#ifdef __mips__ +caddr_t l_offs; /* Load Offset of library */ +#endif +const char *l_name; /* Absolute Path to Library */ +void *l_ld; /* Pointer to .dynamic in memory */ +struct link_map *l_next, /* linked list of mapped libs */ + *l_prev; +.Ed +.Bl -tag -width Va +.It Va l_addr +The base address of the object loaded into memory. +.It Va l_name +The absolute pathname of the loaded shared object. +.It Va l_ld +The address of the dynamic linking information segment +.Pq Dv PT_DYNAMIC +loaded into memory. +.It Va l_next +The next +.Vt Link_map +structure on the link-map list. +.It Va l_prev +The previous +.Vt Link_map +structure on the link-map list. +.El +.\" .It Dv RTLD_DI_SERINFO +.\" Retrieve the library search paths associated with the given +.\" .Fa handle +.\" argument. +.\" The +.\" .Fa p +.\" argument should point to +.\" .Vt Dl_serinfo +.\" structure buffer +.\" .Pq Fa "Dl_serinfo *p" . +.\" The +.\" .Vt Dl_serinfo +.\" structure must be initialized first with the +.\" .Dv RTLD_DI_SERINFOSIZE +.\" request. +.\" .Pp +.\" The returned +.\" .Vt Dl_serinfo +.\" structure contains +.\" .Va dls_cnt +.\" .Vt Dl_serpath +.\" entries. +.\" Each entry's +.\" .Va dlp_name +.\" field points to the search path. +.\" The corresponding +.\" .Va dlp_info +.\" field contains one of more flags indicating the origin of the path (see the +.\" .Dv LA_SER_* +.\" flags defined in the +.\" .In link.h +.\" header file). +.\" See +.\" .Sx EXAMPLES , +.\" example 2, for a usage example. +.\" .It Dv RTLD_DI_SERINFOSIZE +.\" Initialize a +.\" .Vt Dl_serinfo +.\" structure for use in a +.\" .Dv RTLD_DI_SERINFO +.\" request. +.\" Both the +.\" .Va dls_cnt +.\" and +.\" .Va dls_size +.\" fields are returned to indicate the number of search paths applicable +.\" to the handle, and the total size of a +.\" .Vt Dl_serinfo +.\" buffer required to hold +.\" .Va dls_cnt +.\" .Vt Dl_serpath +.\" entries and the associated search path strings. +.\" See +.\" .Sx EXAMPLES , +.\" example 2, for a usage example. +.\" .It Va RTLD_DI_ORIGIN +.\" Retrieve the origin of the dynamic object associated with the handle. +.\" On successful return, +.\" .Fa p +.\" argument is filled with the +.\" .Vt char +.\" pointer +.\" .Pq Fa "char *p" . +.El +.Sh RETURN VALUES +The +.Fn dlinfo +function returns 0 on success, or \-1 if an error occurred. +Whenever an error has been detected, a message detailing it can +be retrieved via a call to +.Xr dlerror 3 . +.Sh EXAMPLES +Using +.Fn dlinfo +to retrieve +.Vt Link_map +structure. +.Pp +The following example shows how dynamic library can detect the list +of shared libraries loaded after caller's one. +For simplicity, error checking has been omitted. +.Bd -literal -offset indent +Link_map *map; + +dlinfo(RTLD_SELF, RTLD_DI_LINKMAP, &map); + +while (map != NULL) { + printf("%p: %s\\n", map->l_addr, map->l_name); + map = map->l_next; +} +.Ed +.\" .Pp +.\" Example 2: Using +.\" .Fn dlinfo +.\" to retrieve the library search paths. +.\" .Pp +.\" The following example shows how a dynamic object can inspect the library +.\" search paths that would be used to locate a simple filename with +.\" .Xr dlopen 3 . +.\" For simplicity, error checking has been omitted. +.\" .Bd -literal -offset indent +.\" Dl_serinfo _info, *info = &_info; +.\" Dl_serpath *path; +.\" unsigned int cnt; +.\" +.\" /* determine search path count and required buffer size */ +.\" dlinfo(RTLD_SELF, RTLD_DI_SERINFOSIZE, (void *)info); +.\" +.\" /* allocate new buffer and initialize */ +.\" info = malloc(_info.dls_size); +.\" info->dls_size = _info.dls_size; +.\" info->dls_cnt = _info.dls_cnt; +.\" +.\" /* obtain search path information */ +.\" dlinfo(RTLD_SELF, RTLD_DI_SERINFO, (void *)info); +.\" +.\" path = &info->dls_serpath[0]; +.\" +.\" for (cnt = 1; cnt <= info->dls_cnt; cnt++, path++) { +.\" (void) printf("%2d: %s\\n", cnt, path->dls_name); +.\" } +.\" .Ed +.Sh SEE ALSO +.Xr rtld 1 , +.Xr dladdr 3 , +.Xr dlopen 3 , +.Xr dlsym 3 +.Sh HISTORY +The +.Fn dlinfo +function first appeared in the Solaris operating system. +In +.Nx , +it first appeared in +.Nx 5.1 . +.Sh AUTHORS +.An -nosplit +The +.Nx +implementation of the +.Fn dlinfo +function was written by +.An Antti Kantee Aq Mt pooka@NetBSD.org . +.Pp +The manual page for this function was written by +.An Alexey Zelkin Aq Mt phantom@FreeBSD.org +and adapted to +.Nx +by +.An Kamil Rytarowski Aq Mt kamil@NetBSD.org . diff --git a/static/netbsd/man3/end.3 b/static/netbsd/man3/end.3 new file mode 100644 index 00000000..5658a0cc --- /dev/null +++ b/static/netbsd/man3/end.3 @@ -0,0 +1,81 @@ +.\" $NetBSD: end.3,v 1.9 2011/04/08 08:47:12 wiz Exp $ +.\" +.\" 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. +.\" +.\" @(#)end.3 6.4 (Berkeley) 1/24/94 +.\" +.Dd September 1, 2005 +.Dt END 3 +.Os +.Sh NAME +.Nm end , +.Nm etext , +.Nm edata +.Nd end boundaries of image segments +.Sh SYNOPSIS +.Vt extern int end; +.Vt extern int etext; +.Vt extern int edata; +.Sh DESCRIPTION +The globals +.Va end , etext +and +.Va edata +are program segment end addresses. +.Pp +.Va etext +is located at the first address after the end of the text segment. +.Pp +.Va edata +is located at the first address after the end of the initialized data segment. +.Pp +.Va end +is located at 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 end +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/netbsd/man3/fast_divide32.3 b/static/netbsd/man3/fast_divide32.3 new file mode 100644 index 00000000..90e44041 --- /dev/null +++ b/static/netbsd/man3/fast_divide32.3 @@ -0,0 +1,113 @@ +.\" $NetBSD: fast_divide32.3,v 1.10 2024/09/07 20:33:53 rillig Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Joerg Sonnenberger. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 10, 2011 +.Dt FAST_DIVIDE32 3 +.Os +.Sh NAME +.Nm fast_divide32 , +.Nm fast_divide32_prepare , +.Nm fast_remainder32 +.Nd fast 32bit division and remainder +.Sh SYNOPSIS +.In sys/bitops.h +.Ft uint32_t +.Fn fast_divide32 "uint32_t v" "uint32_t div" "uint32_t m" "uint8_t s1" \ +"uint8_t s2" +.Ft uint32_t +.Fn fast_remainder32 "uint32_t v" "uint32_t div" "uint32_t m" "uint8_t s1" \ +"uint8_t s2" +.Ft void +.Fn fast_divide32_prepare "uint32_t div" "uint32_t *m" "uint8_t *s1" \ +"uint8_t *s2" +.Sh DESCRIPTION +The +.Nm fast_divide32 +and +.Nm fast_remainder32 +functions compute the equivalent of +.Fa v / Fa div +and +.Fa v % Fa div +using optimised +.Tn CPU +instructions. +The constants +.Fa m , +.Fa s1 , +and +.Fa s2 +must first be preset for a given value of +.Fa div +with the +.Nm fast_divide32_prepare +function. +.Sh RATIONALE +These functions are useful for inner loops and other performance-sensitive +tasks. +The functions expand to code that is typically slightly larger than +a plain division instruction, but requires less time to execute. +The code for constant +.Fa div +arguments should be equivalent to the assembly created by +.Tn GCC . +.Sh EXAMPLES +The following example computes +.Va q = a / b +and +.Va r = a % b : +.Bd -literal -offset indent +uint32_t a, b, q, r, m; +uint8_t s1, s2; + +fast_divide32_prepare(b, &m, &s1, &s2); + +q = fast_divide32(a, b, m, s1, s2); +r = fast_remainder32(a, b, m, s1, s2); +.Ed +.Sh SEE ALSO +.Xr bitops 3 , +.Xr div 3 , +.Xr remainder 3 +.Rs +.%A Torbj\(:orn Granlund +.%A Peter L. Montgomery +.%T Division by Invariant Integers Using Multiplication +.%J ACM SIGPLAN Notices +.%D June 1994 +.%N Issue 6 +.%V Volume 29 +.%P 61-72 +.%U https://gmplib.org/~tege/divcnst-pldi94.pdf +.Re +.Sh HISTORY +The +.Nm +function appeared in +.Nx 6.0 . diff --git a/static/netbsd/man3/ffs32.3 b/static/netbsd/man3/ffs32.3 new file mode 100644 index 00000000..ed40527b --- /dev/null +++ b/static/netbsd/man3/ffs32.3 @@ -0,0 +1,103 @@ +.\" $NetBSD: ffs32.3,v 1.6 2011/04/08 08:47:50 wiz Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 8, 2011 +.Dt FFS32 3 +.Os +.Sh NAME +.Nm ffs32 , +.Nm ffs64 , +.Nm fls32 , +.Nm fls64 +.Nd find first or last bit set +.Sh SYNOPSIS +.In sys/bitops.h +.Ft int +.Fn ffs32 "uint32_t n" +.Ft int +.Fn ffs64 "uint64_t n" +.Ft int +.Fn fls32 "uint32_t n" +.Ft int +.Fn fls64 "uint64_t n" +.Sh DESCRIPTION +The +.Fn ffs32 +and +.Fn ffs64 +functions find the first bit set in +.Fa n +and return the index of that bit. +Conversely, +the +.Fn fls32 +and +.Fn fls64 +functions find the last bit set in +.Fa n , +returning the index of the bit. +.Pp +The search always starts from the bit 1 (the least significant bit). +If the argument +.Fa n +is zero, each function returns zero. +.Sh IMPLEMENTATION NOTES +The described functions are implemented as +.Em static inline +functions in the +.In sys/bitops.h +header. +The standard C library includes a more portable +.Xr ffs 3 +for user applications. +.\" +.\" XXX: It is noted in the CVS history of <sys/bitops.h> that MD-optimized +.\" <machine/bitops.h> is a TODO. If those start to appear, note it here. +.\" +.Sh EXAMPLES +In the following example +.Va f = 3 +and +.Va l = 7 : +.Bd -literal -offset indent +uint32_t n = 0x44; /* 01000100 */ +int f, l; + +f = ffs32(n); +l = fls32(n); +.Ed +.Sh SEE ALSO +.Xr bitops 3 , +.Xr bits 3 , +.Xr bitstring 3 , +.Xr ffs 3 , +.Xr setbit 9 +.Sh HISTORY +These functions first appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/gcq.3 b/static/netbsd/man3/gcq.3 new file mode 100644 index 00000000..cdc0750b --- /dev/null +++ b/static/netbsd/man3/gcq.3 @@ -0,0 +1,532 @@ +.\" $NetBSD: gcq.3,v 1.4 2017/07/03 21:30:58 wiz Exp $ +.\" +.\" Not (c) 2007 Matthew Orgass +.\" This file is public domain, meaning anyone can make any use of part or all +.\" of this file including copying into other works without credit. Any use, +.\" modified or not, is solely the responsibility of the user. If this file +.\" is part of a collection then use in the collection is governed by the +.\" terms of the collection. +.\" +.Dd May 1, 2007 +.Dt GCQ 3 +.Os +.Sh NAME +.Nm GCQ_INIT , +.Nm GCQ_INIT_HEAD , +.Nm gcq_init , +.Nm gcq_init_head , +.Nm gcq_q , +.Nm gcq_hq , +.Nm gcq_head , +.Nm gcq_remove , +.Nm gcq_onlist , +.Nm gcq_empty , +.Nm gcq_linked , +.Nm gcq_insert_after , +.Nm gcq_insert_before , +.Nm gcq_insert_head , +.Nm gcq_insert_tail , +.Nm gcq_tie , +.Nm gcq_tie_after , +.Nm gcq_tie_before , +.Nm gcq_merge , +.Nm gcq_merge_head , +.Nm gcq_merge_tail , +.Nm gcq_clear , +.Nm gcq_remove_all , +.Nm GCQ_ITEM , +.Nm GCQ_GOT_FIRST , +.Nm GCQ_GOT_LAST , +.Nm GCQ_GOT_NEXT , +.Nm GCQ_GOT_PREV , +.Nm GCQ_DEQUEUED_FIRST , +.Nm GCQ_DEQUEUED_LAST , +.Nm GCQ_DEQUEUED_NEXT , +.Nm GCQ_DEQUEUED_PREV , +.Nm GCQ_GOT_FIRST_TYPED , +.Nm GCQ_GOT_LAST_TYPED , +.Nm GCQ_GOT_NEXT_TYPED , +.Nm GCQ_GOT_PREV_TYPED , +.Nm GCQ_DEQUEUED_FIRST_TYPED , +.Nm GCQ_DEQUEUED_LAST_TYPED , +.Nm GCQ_DEQUEUED_NEXT_TYPED , +.Nm GCQ_DEQUEUED_PREV_TYPED , +.Nm GCQ_GOT_FIRST_COND , +.Nm GCQ_GOT_LAST_COND , +.Nm GCQ_GOT_NEXT_COND , +.Nm GCQ_GOT_PREV_COND , +.Nm GCQ_DEQUEUED_FIRST_COND , +.Nm GCQ_DEQUEUED_LAST_COND , +.Nm GCQ_DEQUEUED_NEXT_COND , +.Nm GCQ_DEQUEUED_PREV_COND , +.Nm GCQ_GOT_FIRST_COND_TYPED , +.Nm GCQ_GOT_LAST_COND_TYPED , +.Nm GCQ_GOT_NEXT_COND_TYPED , +.Nm GCQ_GOT_PREV_COND_TYPED , +.Nm GCQ_DEQUEUED_FIRST_COND_TYPED , +.Nm GCQ_DEQUEUED_LAST_COND_TYPED , +.Nm GCQ_DEQUEUED_NEXT_COND_TYPED , +.Nm GCQ_DEQUEUED_PREV_COND_TYPED , +.Nm GCQ_FOREACH , +.Nm GCQ_FOREACH_REV , +.Nm GCQ_FOREACH_NVAR , +.Nm GCQ_FOREACH_NVAR_REV , +.Nm GCQ_FOREACH_RO , +.Nm GCQ_FOREACH_RO_REV , +.Nm GCQ_FOREACH_DEQUEUED , +.Nm GCQ_FOREACH_DEQUEUED_REV , +.Nm GCQ_FOREACH_TYPED , +.Nm GCQ_FOREACH_REV_TYPED , +.Nm GCQ_FOREACH_NVAR_TYPED , +.Nm GCQ_FOREACH_NVAR_REV_TYPED , +.Nm GCQ_FOREACH_RO_TYPED , +.Nm GCQ_FOREACH_RO_REV_TYPED , +.Nm GCQ_FOREACH_DEQUEUED_TYPED , +.Nm GCQ_FOREACH_DEQUEUED_REV_TYPED , +.Nm GCQ_FIND , +.Nm GCQ_FIND_REV , +.Nm GCQ_FIND_TYPED , +.Nm GCQ_FIND_REV_TYPED +.Nd "Generic Circular Queues" +.Sh SYNOPSIS +.In sys/gcq.h +.Pp +.Vt struct gcq ; +.Vt struct gcq_head ; +.Pp +.Fn GCQ_INIT name +.Fn GCQ_INIT_HEAD name +.Pp +.Ft static inline void +.Fn gcq_init "struct gcq *q" +.Ft static inline void +.Fn gcq_init_head "struct gcq_head *head" +.Ft static inline struct gcq * +.Fn gcq_q "struct gcq_head *head" +.Ft static inline struct gcq * +.Fn gcq_hq "struct gcq_head *head" +.Ft static inline struct gcq_head * +.Fn gcq_head "struct gcq *q" +.Ft static inline struct gcq * +.Fn gcq_remove "struct gcq *q" +.Ft static inline bool +.Fn gcq_onlist "struct gcq *q" +.Ft static inline bool +.Fn gcq_empty "struct gcq_head *head" +.Ft static inline bool +.Fn gcq_linked "struct gcq *prev" "struct gcq *next" +.Ft static inline void +.Fn gcq_insert_after "struct gcq *on" "struct gcq *off" +.Ft static inline void +.Fn gcq_insert_before "struct gcq *on" "struct gcq *off" +.Ft static inline void +.Fn gcq_insert_head "struct gcq_head *head" "struct gcq *q" +.Ft static inline void +.Fn gcq_insert_tail "struct gcq_head *head" "struct gcq *q" +.Ft static inline void +.Fn gcq_tie "struct gcq *dst" "struct gcq *src" +.Ft static inline void +.Fn gcq_tie_after "struct gcq *dst" "struct gcq *src" +.Ft static inline void +.Fn gcq_tie_before "struct gcq *dst" "struct gcq *src" +.Ft static inline void +.Fn gcq_merge "struct gcq *dst" "struct gcq *src" +.Ft static inline void +.Fn gcq_merge_tail "struct gcq_head *dst" "struct gcq_head *src" +.Ft static inline void +.Fn gcq_merge_head "struct gcq_head *dst" "struct gcq_head *src" +.Ft static inline void +.Fn gcq_clear "struct gcq *q" +.Ft static inline void +.Fn gcq_remove_all "struct gcq_head *head" +.Pp +.Ft type * +.Fn GCQ_ITEM q type name +.Ft bool +.Fn GCQ_GOT_FIRST var head +.Ft bool +.Fn GCQ_GOT_LAST var head +.Ft bool +.Fn GCQ_GOT_NEXT var current head start +.Ft bool +.Fn GCQ_GOT_PREV var current head start +.Ft bool +.Fn GCQ_DEQUEUED_FIRST var head +.Ft bool +.Fn GCQ_DEQUEUED_LAST var head +.Ft bool +.Fn GCQ_DEQUEUED_NEXT var current head start +.Ft bool +.Fn GCQ_DEQUEUED_PREV var current head start +.Ft bool +.Fn GCQ_GOT_FIRST_TYPED tvar head type name +.Ft bool +.Fn GCQ_GOT_LAST_TYPED tvar head type name +.Ft bool +.Fn GCQ_GOT_NEXT_TYPED tvar current head start type name +.Ft bool +.Fn GCQ_GOT_PREV_TYPED tvar current head start type name +.Ft bool +.Fn GCQ_DEQUEUED_FIRST_TYPED tvar head type name +.Ft bool +.Fn GCQ_DEQUEUED_LAST_TYPED tvar head type name +.Ft bool +.Fn GCQ_DEQUEUED_NEXT_TYPED tvar current head start type name +.Ft bool +.Fn GCQ_DEQUEUED_PREV_TYPED tvar current head start type name +.Ft bool +.Fn GCQ_GOT_FIRST_COND var head cond +.Ft bool +.Fn GCQ_GOT_LAST_COND var head cond +.Ft bool +.Fn GCQ_GOT_NEXT_COND var current head start cond +.Ft bool +.Fn GCQ_GOT_PREV_COND var current head start cond +.Ft bool +.Fn GCQ_DEQUEUED_FIRST_COND var head cond +.Ft bool +.Fn GCQ_DEQUEUED_LAST_COND var head cond +.Ft bool +.Fn GCQ_DEQUEUED_NEXT_COND var current head start cond +.Ft bool +.Fn GCQ_DEQUEUED_PREV_COND var current head start cond +.Ft bool +.Fn GCQ_GOT_FIRST_COND_TYPED tvar head type name cond +.Ft bool +.Fn GCQ_GOT_LAST_COND_TYPED tvar head type name cond +.Ft bool +.Fn GCQ_GOT_NEXT_COND_TYPED tvar current head start type name cond +.Ft bool +.Fn GCQ_GOT_PREV_COND_TYPED tvar current head start type name cond +.Ft bool +.Fn GCQ_DEQUEUED_FIRST_COND_TYPED tvar head type name cond +.Ft bool +.Fn GCQ_DEQUEUED_LAST_COND_TYPED tvar head type name cond +.Ft bool +.Fn GCQ_DEQUEUED_NEXT_COND_TYPED tvar current head start type name cond +.Ft bool +.Fn GCQ_DEQUEUED_PREV_COND_TYPED tvar current head start type name cond +.Fn GCQ_FOREACH var head +.Fn GCQ_FOREACH_REV var head +.Fn GCQ_FOREACH_NVAR var nvar head +.Fn GCQ_FOREACH_NVAR_REV var nvar head +.Fn GCQ_FOREACH_RO var nvar head +.Fn GCQ_FOREACH_RO_REV var nvar head +.Fn GCQ_FOREACH_DEQUEUED var nvar head +.Fn GCQ_FOREACH_DEQUEUED_REV var nvar head +.Fn GCQ_FOREACH_TYPED var head tvar type name +.Fn GCQ_FOREACH_REV_TYPED var head tvar type name +.Fn GCQ_FOREACH_NVAR_TYPED var nvar head tvar type name +.Fn GCQ_FOREACH_NVAR_REV_TYPED var nvar head tvar type name +.Fn GCQ_FOREACH_RO_TYPED var nvar head tvar type name +.Fn GCQ_FOREACH_RO_REV_TYPED var nvar head tvar type name +.Fn GCQ_FOREACH_DEQUEUED_TYPED var nvar head tvar type name +.Fn GCQ_FOREACH_DEQUEUED_REV_TYPED var nvar head tvar type name +.Fn GCQ_FIND var head cond +.Fn GCQ_FIND_REV var head cond +.Fn GCQ_FIND_TYPED var head tvar type name cond +.Fn GCQ_FIND_REV_TYPED var head tvar type name cond +.Fn GCQ_ASSERT cond +.Sh DESCRIPTION +The generic circular queue is a doubly linked list designed for efficient +merge operations and unconditional removal. +All basic operations can be performed with or without use of a separate head, +allowing easy replacement of any pointers where efficient removal is desired. +The meaning of the data type will not change; direct use and defined +operations can be mixed when convenient. +The basic type is: +.Bd -literal -offset indent +struct gcq { + struct gcq *q_next; + struct gcq *q_prev; +}; +.Ed +.Pp +The structure must first be initialized such that the +.Va q_next +and +.Va q_prev +members point to the beginning of the +.Vt struct gcq . +This can be done with +.Fn gcq_init +and +.Fn gcq_init_head +or with constant initializers +.Fn GCQ_INIT +and +.Fn GCQ_INIT_HEAD . +A +.Vt struct gcq +should +.Em never +be given +.Dv NULL +values. +.Pp +The structure containing the +.Vt struct gcq +can be retrieved by pointer arithmetic in the +.Fn GCQ_ITEM +macro. +List traversal normally requires knowledge of the list head to safely +retrieve list items. +.Pp +Capitalized operation names are macros and should be assumed to cause multiple +evaluation of arguments. +.Li TYPED +variants of macros set a typed pointer variable instead of or in addition to +.Vt struct gcq * +arguments. +Additional type specific inlines and macros around some GCQ operations can be +useful. +.Pp +A few assertions are provided when +.Dv DIAGNOSTIC +is defined in the kernel or +.Dv _DIAGNOSTIC +is defined in userland. +If +.Dv GCQ_USE_ASSERT +is defined prior to header inclusions +then +.Fn assert +will be used for assertions and +.Dv NDEBUG +can be used to turn them off. +.Fn GCQ_ASSERT +is a wrapper around the used assertion function. +None of the operations accept +.Dv NULL +arguments, however this is not tested by assertion. +.Pp +The head is separately named for type checking but contains only a +.Vt struct gcq , +a pointer to which can be retrieved via +.Fn gcq_hq . +The reverse operation is performed by +.Fn gcq_head , +turning the supplied +.Vt struct gcq * +into +.Vt struct gcq_head * . +.Fn gcq_q +returns its +.Vt struct gcq * +argument and is used for type checking in +.Fn GCQ_ITEM . +There are no functions for retrieving the raw +.Va q_prev +and +.Va q_next +pointers as these are usually clearer when used directly (if at all). +.Pp +.Fn gcq_remove +returns the element removed and is always a valid operation after +initialization. +.Fn gcq_onlist +returns +.Dv false +if the structure links to itself and +.Dv true +otherwise. +.Fn gcq_empty +is the negation of this operation performed on a head. +.Fn gcq_linked +tests if +.Li "prev->q_next == next && next->q_prev == prev" . +.Pp +.Fn gcq_tie +ties +.Va src +after +.Va dst +such that that if the old lists are DST, DST2 and SRC, SRC2, the new list is +DST, SRC, SRC2, DST2. +If +.Va dst +and +.Va src +are on the same list then any elements between but not including +.Va dst +and +.Va src +are cut from the list. +If +.Li dst == src +then the result is the same as +.Fn gcq_remove . +.Fn gcq_tie +is equivalent to +.Fn gcq_tie_after +except that the latter must only be used with arguments on separate lists or +not on lists and asserts that +.Li "src != dst && dst->q_prev != src" . +.Fn gcq_tie_before +performs the same operation on +.Li dst->q_prev . +.Pp +.Fn gcq_merge +moves any elements on list +.Va src +(but not +.Va src +itself) to list +.Va dst . +It is normally used with two heads via +.Fn gcq_merge_head +or +.Fn gcq_merge_tail . +If +.Dv GCQ_UNCONDITIONAL_MERGE +is defined prior to header inclusion then the merge operations will always +perform a tie then remove +.Va src +from the new list, which may reduce code size slightly. +.Pp +.Fn gcq_clear +initializes all elements currently linked with +.Va q +and is normally used with a head as +.Fn gcq_remove_all . +.Pp +.Fn gcq_insert_after +and +.Fn gcq_insert_before +are slightly optimized versions of +.Fn gcq_tie +for the case where +.Va off +is not on a list and include assertions to this effect, which are also useful +to detect missing initialization. +.Fn gcq_insert_head +and +.Fn gcq_insert_tail +are the same operations applied to a head. +.Pp +.Fn GCQ_GOT_FIRST +and +.Fn GCQ_GOT_LAST +set +.Va var +to a pointer to the first or last +.Vt struct gcq +in the list +or +.Dv NULL +if the list is empty and return +.Dv false +if empty and +.Dv true +otherwise. +The boolean return is to emphasise that it is not normally safe and useful to +directly pass the raw first/next/etc. pointer to another function. +The macros are written such that the +.Dv NULL +values will be optimized out if not otherwise used. +.Li DEQUEUED +variants also remove the member from the list. +.Li COND +variants take an additional condition that is evaluated when the macro would +otherwise return +.Dv true . +If the condition is false +.Va var +or +.Va tvar +is set to +.Dv NULL +and no dequeue is performed. +.Pp +.Fn GCQ_GOT_NEXT +and variants take pointers to the current position, list head, and starting +point as arguments. +The list head will be skipped when it is reached unless it is equal to the +starting point; upon reaching the starting point +.Va var +will be set to +.Dv NULL +and the macro will return +.Dv false . +The next and prev macros also assert that +.Va current +is on the list unless it is equal to +.Va start . +These macros are the only provided method for iterating through the list from +an arbitrary point. +Traversal macros are only provided for list heads, however +.Fn gcq_head +can be used to treat any item as a head. +.Pp +Foreach variants contain an embedded +.Li for +statement for iterating over a list. +Those containing +.Li REV +use the +.Va q_prev +pointer for traversal, others use +.Va q_next . +The plain +.Fn GCQ_FOREACH +uses a single variable. +.Li NVAR +variants save the next pointer at the top of the loop so that the current +element can be removed without adjusting +.Va var . +This is useful when +.Va var +is passed to a function that might remove it but will not otherwise modify +the list. +When the head is reached both +.Va var +and +.Va nvar +elements are left pointing to the list head. +.Li FOREACH +asserts that +.Va var , +and +.Li NVAR +asserts that +.Va nvar +does not point to itself when starting the next loop. +This assertion takes place after the variable is tested against the head so +it is safe to remove all elements from the list. +.Li RO +variants also set +.Va nvar +but assert that the two variables are linked at the end of each iteration. +This is useful when calling a function that is not supposed to remove the +element passed. +.Li DEQUEUED +variants are like +.Li NVAR +but remove each element before the code block is executed. +.Li TYPED +variants are equivalent to the untyped versions except that they take three +extra arguments: a typed pointer, the type name, and the member name of the +.Vt struct gcq +used in this list. +.Va tvar +is set to +.Dv NULL +when the head is reached. +.Pp +.Fn GCQ_FIND +is a foreach loop that does nothing except break when the supplied condition +is true. +.Li REV +and +.Li TYPED +variants are available. +.\" .Sh EXAMPLES +.Sh SEE ALSO +.Xr gcc 1 , +.Xr _DIAGASSERT 3 , +.Xr assert 3 , +.Xr queue 3 , +.Xr KASSERT 9 +.Sh HISTORY +GCQ appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/ilog2.3 b/static/netbsd/man3/ilog2.3 new file mode 100644 index 00000000..f7940844 --- /dev/null +++ b/static/netbsd/man3/ilog2.3 @@ -0,0 +1,85 @@ +.\" $NetBSD: ilog2.3,v 1.6 2021/11/05 22:39:35 riastradh Exp $ $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 5, 2021 +.Dt ILOG2 3 +.Os +.Sh NAME +.Nm ilog2 +.Nd integer base-2 logarithm +.Sh SYNOPSIS +.In sys/bitops.h +.Ft int +.Fn ilog2 "size x" +.Sh DESCRIPTION +For positive +.Fa x , +the +.Fn ilog2 +macro returns the integer part of the base-2 logarithm of +.Fa x ; +that is, +.Fo floor +.Fn log_2 x +.Fc . +If +.Fa n Li = Fn ilog2 x , +then +.Fa n +is the largest integer such that +.No 2** Ns Fa n Li <= Fa x ; +in other words, +.Fn ilog2 +returns the largest integer to which 2 can be raised to obtain a value +at most +.Fa x . +.Pp +The type of the input parameter must be unsigned. +.Pp +If +.Fa x +is a constant expression, then so is +.Fn ilog2 x . +.Sh ERRORS +.Fn ilog2 +returns \-1 when +.Fa x +is zero. +.Sh SEE ALSO +.Xr bitops 3 , +.Xr ffs 3 , +.Xr ilogb 3 , +.Xr log2 3 , +.Xr imax 9 , +.Xr powerof2 9 +.Sh HISTORY +The +.Fn ilog2 +macro first appeared in +.Nx 5.0 . diff --git a/static/netbsd/man3/intro.3 b/static/netbsd/man3/intro.3 new file mode 100644 index 00000000..f7160aa8 --- /dev/null +++ b/static/netbsd/man3/intro.3 @@ -0,0 +1,314 @@ +.\" $NetBSD: intro.3,v 1.38 2025/09/30 10:18:45 uwe Exp $ +.\" +.\" 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. +.\" +.\" @(#)intro.3 8.1 (Berkeley) 6/5/93 +.\" +.Dd April 14, 2021 +.Dt INTRO 3 +.Os +.Sh NAME +.Nm intro +.Nd introduction to the system libraries +.Sh DESCRIPTION +This section provides an overview of the system libraries, their +functions, error returns and other common definitions and concepts. +Most of these functions are available from the standard 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 +.\" A subset of the +.\" .Xr libc functions +.\" are available from Fortran; +.\" they are described separately in +.\" .Xr intro 3f . +.Pp +The various system libraries supplied in +.Nx +(followed by the linker flags) are: +.Bl -tag -width "libc (-lc)" +.It Em libasn1 Pq Fl l Ns Ar asn1 +The abstract syntax notation (ASN) library provides routines for the +specification of abstract data types. +.It Em libbz2 Pq Fl l Ns Ar bz2 +Block-sorting compressor library providing routines for fast and +efficient compression. +.It Em libc Pq Fl l Ns Ar c +The standard C library. +When using the C compiler +.Xr cc 1 , +it is not necessary to supply the linker flag +.Fl l Ns Ar c +for these functions. +There are several subsystems included inside +.Em libc : +.Bl -tag -width "XXXXXX" +.It standard I/O routines +see +.Xr stdio 3 +.It database routines +see +.Xr db 3 +.It bit operators +see +.Xr bitstring 3 +.It string operators +see +.Xr string 3 +.It character tests and character operators +.It encryption and hash routines +see +.Xr md4 3 +and +.Xr md5 3 . +.It storage allocation +see +.Xr mpool 3 +and +.Xr malloc 3 +.It time functions +see +.Xr time 3 +.It signal handling +see +.Xr signal 3 +.El +.It Em libcom_err Pq Fl l Ns Ar com_err +The common error description library. +See +.Xr com_err 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 libcrypt Pq Fl l Ns Ar crypt +The crypt library. +See +.Xr crypt 3 . +.It Em libcrypto Pq Fl l Ns Ar crypto +The OpenSSL cryptographic library. +See +.Xr crypto 7 . +.It Em libcurses Pq Fl l Ns Ar curses Fl l Ns Ar terminfo +Terminal independent screen management routines +for two dimensional non-bitmap display terminals. +See +.Xr curses 3 . +.It Em libdes Pq Fl l Ns Ar des +The OpenSSL cryptographic library for the DES algorithms. +See +.Xr des 3 . +.It Em libdm Pq Fl l Ns Ar dm +The device-mapper driver access library used for communication with +kernel driver +.Xr dm 4 +and for +.Xr lvm 8 +subsystem. +.It Em libedit Pq Fl l Ns Ar edit +The command-line editor or editline library. +The editline library provides generic editing and history functions. +See +.Xr editline 3 . +.It Em libform Pq Fl l Ns Ar form +The curses form library provides a terminal-independent form system +using the curses library. +The form library provides facilities for defining forms on terminals. +See +.Xr forms 3 . +.It Em libgssapi Pq Fl l Ns Ar gssapi +The Generic Security Services (GSS) API library. +This library provides +verification services to applications and usually sits above the +cryptographic libraries. +.It Em libhdb Pq Fl l Ns Ar hdb +The Heimdal Kerberos 5 authentication/authorisation database access +library. +.It Em libintl Pq Fl l Ns Ar intl +The internationalized message handling library. +See +.Xr gettext 3 . +.It Em libipsec Pq Fl l Ns Ar ipsec +The IPsec policy control library. +See +.Xr ipsec_set_policy 3 +and +.Xr ipsec_strerror 3 . +.It Em libkadm5clnt Pq Fl l Ns Ar kadm5clnt +The Kerberos 5 administration client library. +.It Em libkadm5srv Pq Fl l Ns Ar kadm5srv +The Kerberos 5 administration server library. +See +.Xr kadm5_pwcheck 3 . +.It Em libkafs Pq Fl l Ns Ar kafs +The Kerberos IV AFS library. +See +.Xr kafs 3 . +.It Em libkdb Pq Fl l Ns Ar kdb +The Kerberos IV authentication/authorisation database access library. +.It Em libkrb Pq Fl l Ns Ar krb +The Kerberos IV library. +.It Em libkrb5 Pq Fl l Ns Ar krb5 +The Kerberos 5 library. +See +.Xr krb5 3 . +.It Em libkstream Pq Fl l Ns Ar kstream +Kerberos IV encrypted stream library. +.It Em libkvm Pq Fl l Ns Ar kvm +Kernel data access library. +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 . +.\" The math library is loaded as needed by the Pascal compiler +.\" .Xr pc 1 , +.\" but not by the C compiler which requires the +.\" .Fl l Ns Ar m +.\" flag (see +.\" .Xr math 3 ) . +.\" .It Em libmp Pq Fl l Ns Ar mp +.\" .It Em libom +.\" Old math library. +.\" .It Em libplot Pq Fl l Ns Ar plot +.\" Device independent plotting functions (see +.\" .Xr plot 3 ) . +.\" .It Em libplotf77 Pq Fl l Ns Ar plotf77 +.\" The device independent plotting functions for fortran (see +.\" .Xr plot 3 ) . +.\" .It Em libresolv Pq Fl l Ns Ar resolv +.\" Routines for network address resolution. +.It Em libmenu Pq Fl l Ns Ar menu +The curses menu library. +See +.Xr menus 3 . +.It Em libnvmm Pq Fl l Ns Ar nvmm +.Nx +Virtualization API. +See +.Xr libnvmm 3 . +.It Em libossaudio Pq Fl l Ns Ar ossaudio +Open Sound System compatibility library. +See +.Xr ossaudio 3 . +.It Em libpanel Pq Fl l Ns Ar panel +The curses panel library. +See +.Xr panel 3 . +.It Em libpcap Pq Fl l Ns Ar pcap +The packet capture library. +See +.Xr pcap 3 . +.It Em libpci Pq Fl l Ns Ar pci +The PCI bus access library. +See +.Xr pci 3 . +.It Em libposix Pq Fl l Ns Ar posix +The POSIX compatibility library provides a compatibility interface for +POSIX functions which differ from the standard BSD interfaces. +See +.Xr chown 2 +and +.Xr rename 2 . +.It Em libresolv Pq Fl l Ns Ar resolv +The DNS resolver library. +.It Em librmt Pq Fl l Ns Ar rmt +Remote magnetic tape library. +See +.Xr rmtops 3 . +.It Em libroken Pq Fl l Ns Ar roken +A library containing compatibility functions used by Kerberos. +It implements functionality required by the Kerberos implementation not +implemented in the standard +.Nx +libraries. +.It Em librpcsvc Pq Fl l Ns Ar rpcsvc +The Remote Procedure Call (RPC) services library. +See +.Xr rpc 3 . +.It Em libskey Pq Fl l Ns Ar skey +The S/Key one-time password library. +See +.Xr skey 3 . +.It Em libsl Pq Fl l Ns Ar sl +.It Em libss Pq Fl l Ns Ar ss +.It Em libssl Pq Fl l Ns Ar ssl +The secure sockets layer (SSL) library. +See +.Xr ssl 7 . +.It Em libtelnet Pq Fl l Ns Ar telnet +The telnet library. +.It Em libterminfo Pq Fl l Ns Ar terminfo +The terminal-independent operation library. +See +.Xr terminfo 3 . +.It Em libusbhid Pq Fl l Ns Ar usbhid +The Universal Serial Bus (USB) Human Interface Devices access library. +See +.Xr libusbhid 3 . +.It Em libutil Pq Fl l Ns Ar util +The system utilities library. +See +.Xr util 3 . +.It Em libwrap Pq Fl l Ns Ar wrap +The TCP wrappers library. +See +.Xr hosts_access 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 +General-purpose compression library. +See +.Xr zlib 3 . +.El +.Sh SEE ALSO +.Xr cc 1 , +.Xr ld 1 , +.Xr nm 1 , +.Xr rtld 1 , +.Xr intro 2 +.Sh HISTORY +An +.Nm +manual appeared in +.At v7 . diff --git a/static/netbsd/man3/inttypes.3 b/static/netbsd/man3/inttypes.3 new file mode 100644 index 00000000..afbfeed9 --- /dev/null +++ b/static/netbsd/man3/inttypes.3 @@ -0,0 +1,152 @@ +.\" $NetBSD: inttypes.3,v 1.2 2010/05/14 02:45:27 joerg Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 21, 2010 +.Dt INTTYPES 3 +.Os +.Sh NAME +.Nm inttypes +.Nd standard fixed-size integer types +.Sh SYNOPSIS +.In inttypes.h +.Sh DESCRIPTION +The +.In inttypes.h +header describes a set of format specifier macros aimed to increase +portability both within and across operating systems. +It includes the +.In stdint.h +header and extends it with additional facilities. +.Pp +Each of the following macros expand to a character string literal +containing the format specifier suitable for use within the format +argument of a formatted +.Tn I/O +function such as +.Xr printf 3 . +Each macro contains an identifier (PRI or SCN), +a conversion specifier, and a possible length modifier. +.Pp +The length modifier follows the integer types described in +.Xr stdint 3 : +.Bl -column -offset indent \ +"PRIdLEAST64 " \ +"PRIdLEAST64 " +.It Em int8_t Ta Em uint8_t +.It Em int16_t Ta Em uint16_t +.It Em int32_t Ta Em uint32_t +.It Em int64_t Ta Em uint64_t +.It Em int_least8_t Ta Em uint_least8_t +.It Em int_least16_t Ta Em uint_least16_t +.It Em int_least32_t Ta Em uint_least32_t +.It Em int_least64_t Ta Em uint_least64_t +.It Em int_fast8_t Ta Em uint_fast8_t +.It Em int_fast16_t Ta Em uint_fast16_t +.It Em int_fast32_t Ta Em uint_fast32_t +.It Em int_fast64_t Ta Em uint_fast64_t +.It Em intmax_t Ta Em uintmax_t +.It Em intptr_t Ta Em uintptr_t +.El +.Pp +The following format specifiers are defined for the +.Xr fprintf 3 +and +.Xr fscanf 3 +families, respectively: +.Bl -column -offset indent \ +"PRIdLEAST64 " \ +"PRIdLEAST64 " +.It Li PRI?8 Ta Li SCN?8 +.It Li PRI?16 Ta Li SCN?16 +.It Li PRI?32 Ta Li SCN?32 +.It Li PRI?64 Ta Li SCN?64 +.It Li PRI?LEAST8 Ta Li SCN?LEAST8 +.It Li PRI?LEAST16 Ta Li SCN?LEAST16 +.It Li PRI?LEAST32 Ta Li SCN?LEAST32 +.It Li PRI?LEAST64 Ta Li SCN?LEAST64 +.It Li PRI?FAST8 Ta Li SCN?FAST8 +.It Li PRI?FAST16 Ta Li SCN?FAST16 +.It Li PRI?FAST32 Ta Li SCN?FAST32 +.It Li PRI?FAST64 Ta Li SCN?FAST64 +.It Li PRI?MAX Ta Li SCN?MAX +.It Li PRI?PTR Ta Li SCN?PTR +.El +.Pp +The available conversion specifiers, +.Dq \&? +in above, are +.Em d +and +.Em i +for signed integers and +.Em o , +.Em u , +.Em x , +and +.Em X +for unsigned integers. +The +.Em X +is not available for the +.Xr fscanf 3 +family. +Without the length modifier these would correspond with +.Sy \&%d , +.Sy \&%i , +.Sy \&%o , +.Sy \&%u , +.Sy \&%x , +and +.Sy \&%X , +respectively. +.Sh EXAMPLES +The following example demonstrates typical usage: +.Bd -literal -offset indent +uint64_t i = 123; + +\&... + +(void)printf("i = %"PRIu64"\en", i); +.Ed +.Sh SEE ALSO +.Xr printf 3 , +.Xr scanf 3 , +.Xr stdint 3 +.Sh STANDARDS +The +.In inttypes.h +header conforms to +.St -isoC-99 +and +.St -p1003.1-2001 . +.Sh HISTORY +The +.In inttypes.h +header was first introduced in +.Nx 1.6 . diff --git a/static/netbsd/man3/iso646.3 b/static/netbsd/man3/iso646.3 new file mode 100644 index 00000000..42a7b833 --- /dev/null +++ b/static/netbsd/man3/iso646.3 @@ -0,0 +1,71 @@ +.\" $NetBSD: iso646.3,v 1.6 2017/07/03 21:30:58 wiz Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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, 2010 +.Dt ISO646 3 +.Os +.Sh NAME +.Nm iso646 +.Nd alternative operator spellings +.Sh SYNOPSIS +.In iso646.h +.Sh DESCRIPTION +The +.In iso646.h +header defines eleven alternative spellings for standard operators: +.Bl -column -offset indent \ +"11." "xor_eq" "xx" +.It Li 1. Ta Em and Ta && +.It Li 2. Ta Em and_eq Ta &\&= +.It Li 3. Ta Em bitand Ta & +.It Li 4. Ta Em bitor Ta \*[Ba] +.It Li 5. Ta Em compl Ta \&~ +.It Li 6. Ta Em not Ta \&! +.It Li 7. Ta Em not_eq Ta \*[Ne] +.It Li 8. Ta Em or Ta \*[Ba]\*[Ba] +.It Li 9. Ta Em or_eq Ta \*[Ba]\&= +.It Li 10. Ta Em xor Ta \&^ +.It Li 11. Ta Em xor_eq Ta \&^\&= +.El +.Pp +Each macro expands to the corresponding token. +.Sh RATIONALE +None. +.Sh SEE ALSO +.Xr operator 7 +.Sh STANDARDS +The +.In iso646.h +header conforms to +.St -ansiC . +.Sh HISTORY +The +.In iso646.h +header was first introduced in +.Nx 1.1 . diff --git a/static/netbsd/man3/limits.3 b/static/netbsd/man3/limits.3 new file mode 100644 index 00000000..a2a435b1 --- /dev/null +++ b/static/netbsd/man3/limits.3 @@ -0,0 +1,171 @@ +.\" $NetBSD: limits.3,v 1.2 2011/08/29 16:56:32 njoly Exp $ +.\" +.\" Copyright (c) 2011 Jukka Ruohonen <jruohonen@iki.fi> +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 9, 2011 +.Dt LIMITS 3 +.Os +.Sh NAME +.Nm limits +.Nd standard limits +.Sh SYNOPSIS +.In limits.h +.Sh DESCRIPTION +The +.In limits.h +header defines various compile-time and runtime limits. +These can be grouped into three categories: +.Bl -enum -offset indent +.It +Compile-time limits defined in a header file. +.It +Runtime system limits that are not associated with a file or directory; see +.Xr sysconf 3 . +.It +Runtime limits that are associated with a file or directory; see +.Xr pathconf 2 . +.El +.Pp +The +.In limits.h +header has been standardized by at least three entities. +.Ss ISO Limits +The limits defined by the +.St -isoC-99 +standard are all compile-time limits. +The numerical (integer) limits are: +.Bl -column -offset indent \ +"Constant " " Type " "either SCHAR_MAX or UCHAR_MAX " +.It Sy "Constant" Ta Sy "Type" Ta Sy " Minimum value" +.It Dv CHAR_BIT Ta Va char Ta " 8" +.It Dv SCHAR_MAX Ta Va signed char Ta " 127" +.It Dv SCHAR_MIN Ta Va signed char Ta "\-127" +.It Dv UCHAR_MAX Ta Va unsigned char Ta " 255" +.Pp +.It Dv INT_MAX Ta Va int Ta " 32767" +.It Dv INT_MIN Ta Va int Ta "\-32767" +.It Dv UINT_MAX Ta Va unsigned int Ta " 65535" +.Pp +.It Dv SHRT_MIN Ta Va short Ta "\-32767" +.It Dv SHRT_MAX Ta Va short Ta " 32767" +.It Dv USHRT_MAX Ta Va unsigned short Ta " 65535" +.Pp +.It Dv LONG_MAX Ta Va long int Ta " 2147483647" +.It Dv LONG_MIN Ta Va long int Ta "\-2147483647" +.It Dv ULONG_MAX Ta Va unsigned long int Ta " 4294967295" +.Pp +.It Dv LLONG_MAX Ta Va long long int Ta " 9223372036854775807" +.It Dv LLONG_MIN Ta Va long long int Ta "\-9223372036854775807" +.It Dv ULLONG_MAX Ta Va unsigned long long int Ta " 18446744073709551615" +.Pp +.It Dv MB_LEN_MAX Ta - Ta 1 +.El +.Pp +All listed limits may vary across machines and operating systems. +The standard guarantees only that the implementation-defined values are +equal or greater in absolute value to those shown. +The values permit a system with 16-bit integers +using one's complement arithmetic. +.Pp +Depending whether the system defines +.Va char +as signed or unsigned, the maximum and minimum values are: +.Bl -column -offset indent \ +"Constant " " Type " "either SCHAR_MAX or UCHAR_MAX " +.It Sy "Constant" Ta Sy "Type" Ta Sy "Minimum value" +.It Dv CHAR_MAX Ta Va char Ta either Dv SCHAR_MAX or Dv UCHAR_MAX +.It Dv CHAR_MIN Ta Va char Ta either Dv SCHAR_MIN or 0 +.El +.Pp +The two special cases, +.Dv CHAR_BIT +and +.Dv MB_LEN_MAX , +define the number of bits in +.Va char +and the maximum number of bytes in a multibyte character constant, +respectively. +.Ss POSIX Limits +The +.Dv POSIX.1 +standard specifies numerous limits related to the operating system. +For each limit, a separate constant prefixed with +.Dq Dv _POSIX_ +defines the +.Em lowest +value that the limit is allowed to have on +.Em any +.Tn POSIX +compliant system. +For instance, +.Dv _POSIX_OPEN_MAX +defines the minimum upper bound permitted by +.Tn POSIX +for the number of files that a single process may have open at any time. +This ensures that a portable program can safely reach these limits without +prior knowledge about the actual limits used in a particular system. +.Pp +As the limits are not necessary invariant, +.Xr pathconf 2 +and +.Xr sysconf 3 +should be used to determine the actual value of a limit at runtime. +The manual pages of these two functions also contain a more detailed +description of the limits available in +.Nx . +.Ss XSI Limits +Also the X/Open System Interface Extension +.Pq Dv XSI +specifies few limits. +In +.Nx +these are limited to +.Dv LONG_BIT +(the number of bits in +.Vt long ) , +.Dv WORD_BIT +(the number of bits in a +.Dq word ) , +and few limits related to +.Vt float +and +.Vt double . +.Sh SEE ALSO +.Xr getconf 1 , +.Xr pathconf 2 , +.Xr sysconf 3 , +.Xr types 3 , +.Xr unistd 3 +.Rs +.%A Richard W. Stevens +.%A Stephen A. Rago +.%B Advanced Programming in the UNIX Environment +.%V Second Edition +.%D 2005 +.%I Addison-Wesley +.Re diff --git a/static/netbsd/man3/makedev.3 b/static/netbsd/man3/makedev.3 new file mode 100644 index 00000000..a2a8e927 --- /dev/null +++ b/static/netbsd/man3/makedev.3 @@ -0,0 +1,80 @@ +.\" $NetBSD: makedev.3,v 1.3 2026/04/09 16:10:49 christos Exp $ +.\" +.\" 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. +.\" +.\" $FreeBSD: src/share/man/man3/makedev.3,v 1.2 2008/09/28 20:26:16 ed Exp $ +.\" +.Dd April 9, 2026 +.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 allows a unique device number to be generated based on its +.Fa major +and +.Fa minor +number. +The +.Fn major +and +.Fn minor +macros can be used to obtain the original numbers from the device number +.Fa dev . +.Pp +All block and character devices are uniquely +identified by a pair of major and minor numbers. +The major number refers to a certain device class (e.g. disks, TTYs) +while the minor number identifies an instance within the device class. +.Sh RETURN VALUES +The +.Fn major +macro returns a device major number that has a value between 0 and 4095 (0xfff). +The +.Fn minor +macro returns a device minor number that has a value between 0 and 1048575 +(0xfffff). +.Sh SEE ALSO +.Xr mknod 2 , +.Xr devname 3 , +.Xr MAKEDEV 8 +.Sh HISTORY +The major and minor numbers used to support values between 0 and 255 +(0xff) until +.Nx 1.3 +when the macros were changed to support their current ranges. diff --git a/static/netbsd/man3/offsetof.3 b/static/netbsd/man3/offsetof.3 new file mode 100644 index 00000000..7b6fb29a --- /dev/null +++ b/static/netbsd/man3/offsetof.3 @@ -0,0 +1,72 @@ +.\" $NetBSD: offsetof.3,v 1.5 2011/04/14 06:56:28 wiz Exp $ +.\" +.\" $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 April 1, 2011 +.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 EXAMPLES +Regardless of the architecture and the +.Tn ABI , +the following example prints the value zero for the variable +.Va x . +.Bd -literal -offset indent +struct example { + double x; + int y; + char z; +}; + +size_t x, y, z; + +x = offsetof(struct example, x); +y = offsetof(struct example, y); +z = offsetof(struct example, z); + +(void)printf("%zu %zu %zu\en", x, y, z); +.Ed +.Sh SEE ALSO +.Xr __alignof__ 3 , +.Xr stddef 3 , +.Xr typeof 3 +.Sh STANDARDS +The +.Fn offsetof +macro conforms to +.St -ansiC . diff --git a/static/netbsd/man3/param.3 b/static/netbsd/man3/param.3 new file mode 100644 index 00000000..449f3d46 --- /dev/null +++ b/static/netbsd/man3/param.3 @@ -0,0 +1,101 @@ +.\" $NetBSD: param.3,v 1.4 2011/04/10 10:02:34 jruoho Exp $ +.\" +.\" Copyright (c) 2011 Jukka Ruohonen <jruohonen@iki.fi> +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 10, 2011 +.Dt PARAM 3 +.Os +.Sh NAME +.Nm param +.Nd common parameters +.Sh SYNOPSIS +.In sys/param.h +.Ft size +.Fn MAX "size a" "size b" +.Ft size +.Fn MIN "size a" "size b" +.Sh DESCRIPTION +The +.In sys/param.h +header includes some common definitions and macros specific to +.Nx . +The header is perhaps best characterized as a kernel equivalent of +.In sys/types.h . +The following list summarizes the provided definitions and macros. +.Bl -bullet -offset indent +.It +First and foremost, the header defines the version of +.Nx . +This is defined as +.Bd -literal -offset indent +#define __NetBSD_Version__ 599004800 /* 5.99.48 */ +.Ed +.Pp +The general format is +.Dq MMmmrrpp00 , +where +.Sq MM +and +.Sq mm +denote the major and minor version, respectively, +.Sq rr +is provided for compatibility, and +.Sq pp +defines the patch level. +.It +Common utility macros such as +.Fn MAX +and +.Fn MIN +as well as more specific macros such as +.Xr STACK 9 , +.Xr ctod 9 , +.Xr mstohz 9 , +.Xr roundup 9 , +and +.Xr setbit 9 . +.It +Numerous miscellaneous definitions such as limits, +constants for the kernel +.Xr memoryallocators 9 , +scale factors used by the scheduler, +.Xr kthread 9 +priorities, and many others. +.It +Definitions provided for historical and compatibility reasons. +Examples range from definitions such as +.Dq #define BSD +to old priority levels used in the kernel. +.El +.Sh SEE ALSO +.Xr bitops 3 , +.Xr cdefs 3 , +.Xr types 3 , +.Xr unistd 3 +.Sh HISTORY +A +.In param.h +header appeared already in the +.At v4 . diff --git a/static/netbsd/man3/paths.3 b/static/netbsd/man3/paths.3 new file mode 100644 index 00000000..e77a984b --- /dev/null +++ b/static/netbsd/man3/paths.3 @@ -0,0 +1,98 @@ +.\" $NetBSD: paths.3,v 1.3 2011/04/08 08:12:51 jruoho Exp $ +.\" +.\" Copyright (c) 2011 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 8, 2011 +.Dt PATHS 3 +.Os +.Sh NAME +.Nm paths +.Nd default system paths +.Sh SYNOPSIS +.In paths.h +.Sh DESCRIPTION +The +.In paths.h +header defines some default paths used in +.Nx . +All defined constants are prefixed with +.Dv _PATH . +The constants include: +.Bl -bullet -offset indent +.It +The default user search path set by +.Xr login 1 +and associated utilities such as +.Xr rshd 8 . +This is defined by +.Dv _PATH_DEFPATH +and includes directories such as +.Pa /usr/bin +and +.Pa /usr/local/bin . +.It +Default paths for some utilities and device nodes. +Examples include such paths as +.Pa /dev/null +.Pq Dv _PATH_DEVNULL , +.Pa /dev/mem +.Pq Dv _PATH_MEM , +and +.Pa /etc/nologin +.Pq Dv _PATH_NOLOGIN , +among others. +.It +Paths for some default directories such as +.Pa /dev +.Pq Dv _PATH_DEV +and +.Pa /tmp +.Pq Dv _PATH_TMP +as well as paths for some miscellaneous utilities such as +.Xr csh 1 , +.Pa /bin/csh +.Pq Dv _PATH_CSHELL . +.El +.Sh SEE ALSO +.Xr whereis 1 , +.Xr sysexits 3 , +.Xr types 3 , +.Xr hier 7 +.\" +.\" XXX: Fill this. +.\" +.\" .Sh HISTORY +.\" The +.\" .In paths.h +.\" header first appeared in +.\" .Bx ???? +.Sh CAVEATS +The +.In paths.h +header is specific to +.Nx . diff --git a/static/netbsd/man3/queue.3 b/static/netbsd/man3/queue.3 new file mode 100644 index 00000000..095c5b7c --- /dev/null +++ b/static/netbsd/man3/queue.3 @@ -0,0 +1,1103 @@ +.\" $NetBSD: queue.3,v 1.61 2020/10/20 23:27:57 kamil Exp $ +.\" +.\" Copyright (c) 2000, 2002 The NetBSD Foundation, 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. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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) 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. +.\" +.\" @(#)queue.3 8.1 (Berkeley) 12/13/93 +.\" +.Dd October 1, 2017 +.Dt QUEUE 3 +.Os +.Sh NAME +.Nm SLIST_HEAD , +.Nm SLIST_HEAD_INITIALIZER , +.Nm SLIST_ENTRY , +.Nm SLIST_FIRST , +.Nm SLIST_EMPTY , +.Nm SLIST_NEXT , +.Nm SLIST_FOREACH , +.Nm SLIST_FOREACH_SAFE , +.Nm SLIST_INIT , +.Nm SLIST_INSERT_AFTER , +.Nm SLIST_INSERT_HEAD , +.Nm SLIST_REMOVE_AFTER , +.Nm SLIST_REMOVE_HEAD , +.Nm SLIST_REMOVE , +.Nm LIST_HEAD , +.Nm LIST_HEAD_INITIALIZER , +.Nm LIST_ENTRY , +.Nm LIST_FIRST , +.Nm LIST_EMPTY , +.Nm LIST_NEXT , +.Nm LIST_FOREACH , +.Nm LIST_FOREACH_SAFE , +.Nm LIST_INIT , +.Nm LIST_INSERT_AFTER , +.Nm LIST_INSERT_BEFORE , +.Nm LIST_INSERT_HEAD , +.Nm LIST_REMOVE , +.Nm LIST_REPLACE , +.Nm LIST_MOVE , +.Nm SIMPLEQ_HEAD , +.Nm SIMPLEQ_HEAD_INITIALIZER , +.Nm SIMPLEQ_ENTRY , +.Nm SIMPLEQ_FIRST , +.Nm SIMPLEQ_EMPTY , +.Nm SIMPLEQ_NEXT , +.Nm SIMPLEQ_LAST , +.Nm SIMPLEQ_FOREACH , +.Nm SIMPLEQ_FOREACH_SAFE , +.Nm SIMPLEQ_INIT , +.Nm SIMPLEQ_INSERT_AFTER , +.Nm SIMPLEQ_INSERT_HEAD , +.Nm SIMPLEQ_INSERT_TAIL , +.Nm SIMPLEQ_REMOVE_AFTER , +.Nm SIMPLEQ_REMOVE_HEAD , +.Nm SIMPLEQ_REMOVE , +.Nm SIMPLEQ_CONCAT , +.Nm TAILQ_HEAD , +.Nm TAILQ_HEAD_INITIALIZER , +.Nm TAILQ_ENTRY , +.Nm TAILQ_FIRST , +.Nm TAILQ_NEXT , +.Nm TAILQ_LAST , +.Nm TAILQ_PREV , +.Nm TAILQ_EMPTY , +.Nm TAILQ_FOREACH , +.Nm TAILQ_FOREACH_SAFE , +.Nm TAILQ_FOREACH_REVERSE , +.Nm TAILQ_FOREACH_REVERSE_SAFE , +.Nm TAILQ_INIT , +.Nm TAILQ_INSERT_AFTER , +.Nm TAILQ_INSERT_BEFORE , +.Nm TAILQ_INSERT_HEAD , +.Nm TAILQ_INSERT_TAIL , +.Nm TAILQ_REMOVE , +.Nm TAILQ_REPLACE , +.Nm TAILQ_CONCAT , +.Nm STAILQ_HEAD , +.Nm STAILQ_HEAD_INITIALIZER , +.Nm STAILQ_ENTRY , +.Nm STAILQ_FIRST , +.Nm STAILQ_EMPTY , +.Nm STAILQ_NEXT , +.Nm STAILQ_LAST , +.Nm STAILQ_FOREACH , +.Nm STAILQ_FOREACH_SAFE , +.Nm STAILQ_INIT , +.Nm STAILQ_INSERT_AFTER , +.Nm STAILQ_INSERT_HEAD , +.Nm STAILQ_INSERT_TAIL , +.Nm STAILQ_REMOVE_HEAD , +.Nm STAILQ_REMOVE , +.Nm STAILQ_CONCAT +.Nd implementations of singly-linked lists, lists, simple queues, tail queues, and singly-linked tail queues +.Sh SYNOPSIS +.In sys/queue.h +.Pp +.Fn SLIST_HEAD "HEADNAME" "TYPE" +.Fn SLIST_HEAD_INITIALIZER "head" +.Fn SLIST_ENTRY "TYPE" +.Ft TYPE * +.Fn SLIST_FIRST "SLIST_HEAD *head" +.Ft int +.Fn SLIST_EMPTY "SLIST_HEAD *head" +.Ft TYPE * +.Fn SLIST_NEXT "TYPE *elm" "SLIST_ENTRY NAME" +.Fn SLIST_FOREACH "TYPE *var" "SLIST_HEAD *head" "SLIST_ENTRY NAME" +.Fn SLIST_FOREACH_SAFE "TYPE *var" "SLIST_HEAD *head" "SLIST_ENTRY NAME" "TYPE *tmp" +.Fn SLIST_INIT "SLIST_HEAD *head" +.Fn SLIST_INSERT_HEAD "SLIST_HEAD *head" "TYPE *elm" "SLIST_ENTRY NAME" +.Fn SLIST_INSERT_AFTER "TYPE *listelm" "TYPE *elm" "SLIST_ENTRY NAME" +.Fn SLIST_REMOVE "SLIST_HEAD *head" "TYPE *elm" "TYPE" "SLIST_ENTRY NAME" +.Fn SLIST_REMOVE_HEAD "SLIST_HEAD *head" "SLIST_ENTRY NAME" +.Pp +.Fn LIST_HEAD "HEADNAME" "TYPE" +.Fn LIST_HEAD_INITIALIZER "head" +.Fn LIST_ENTRY "TYPE" +.Ft TYPE * +.Fn LIST_FIRST "LIST_HEAD *head" +.Ft TYPE * +.Fn LIST_NEXT "TYPE *elm" "LIST_ENTRY NAME" +.Ft int +.Fn LIST_EMPTY "LIST_HEAD *head" +.Fn LIST_FOREACH "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" +.Fn LIST_FOREACH_SAFE "TYPE *var" "LIST_HEAD *head" "LIST_ENTRY NAME" "TYPE *tmp" +.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_REMOVE "TYPE *elm" "LIST_ENTRY NAME" +.Fn LIST_REPLACE "TYPE *elm" "TYPE *new" "LIST_ENTRY NAME" +.Fn LIST_MOVE "LIST_HEAD *head1" "LIST_HEAD *head2" "LIST_ENTRY NAME" +.Pp +.Fn SIMPLEQ_HEAD "HEADNAME" "TYPE" +.Fn SIMPLEQ_HEAD_INITIALIZER "head" +.Fn SIMPLEQ_ENTRY "TYPE" +.Ft TYPE * +.Fn SIMPLEQ_FIRST "SIMPLEQ_HEAD *head" +.Ft int +.Fn SIMPLEQ_EMPTY "SIMPLEQ_HEAD *head" +.Ft TYPE * +.Fn SIMPLEQ_NEXT "TYPE *elm" "SIMPLEQ_ENTRY NAME" +.Ft TYPE * +.Fn SIMPLEQ_LAST "SIMPLEQ_HEAD *head" "TYPE *elm" "SIMPLEQ_ENTRY NAME" +.Fn SIMPLEQ_FOREACH "TYPE *var" "SIMPLEQ_HEAD *head" "SIMPLEQ_ENTRY NAME" +.Fn SIMPLEQ_FOREACH_SAFE "TYPE *var" "SIMPLEQ_HEAD *head" "SIMPLEQ_ENTRY NAME" "TYPE *tmp" +.Fn SIMPLEQ_INIT "SIMPLEQ_HEAD *head" +.Fn SIMPLEQ_INSERT_HEAD "SIMPLEQ_HEAD *head" "TYPE *elm" "SIMPLEQ_ENTRY NAME" +.Fn SIMPLEQ_INSERT_TAIL "SIMPLEQ_HEAD *head" "TYPE *elm" "SIMPLEQ_ENTRY NAME" +.Fn SIMPLEQ_INSERT_AFTER "SIMPLEQ_HEAD *head" "TYPE *listelm" "TYPE *elm" "SIMPLEQ_ENTRY NAME" +.Fn SIMPLEQ_REMOVE_HEAD "SIMPLEQ_HEAD *head" "SIMPLEQ_ENTRY NAME" +.Fn SIMPLEQ_REMOVE_AFTER "SIMPLEQ_HEAD *head" "TYPE *elm" "SIMPLEQ_ENTRY NAME" +.Fn SIMPLEQ_REMOVE "SIMPLEQ_HEAD *head" "TYPE *elm" "TYPE" "SIMPLEQ_ENTRY NAME" +.Fn SIMPLEQ_CONCAT "SIMPLEQ_HEAD *head1" "SIMPLEQ_HEAD *head2" +.Pp +.Fn TAILQ_HEAD "HEADNAME" "TYPE" +.Fn TAILQ_HEAD_INITIALIZER "head" +.Fn TAILQ_ENTRY "TYPE" +.Ft TYPE * +.Fn TAILQ_FIRST "TAILQ_HEAD *head" +.Ft TYPE * +.Fn TAILQ_NEXT "TYPE *elm" "TAILQ_ENTRY NAME" +.Ft TYPE * +.Fn TAILQ_LAST "TAILQ_HEAD *head" "HEADNAME" +.Ft TYPE * +.Fn TAILQ_PREV "TYPE *elm" "HEADNAME" "TAILQ_ENTRY NAME" +.Ft int +.Fn TAILQ_EMPTY "TAILQ_HEAD *head" +.Fn TAILQ_FOREACH "TYPE *var" "TAILQ_HEAD *head" "TAILQ_ENTRY NAME" +.Fn TAILQ_FOREACH_SAFE "TYPE *var" "TAILQ_HEAD *head" "TAILQ_ENTRY NAME" "TYPE *tmp" +.Fn TAILQ_FOREACH_REVERSE "TYPE *var" "TAILQ_HEAD *head" "HEADNAME" "TAILQ_ENTRY NAME" +.Fn TAILQ_FOREACH_REVERSE_SAFE "TYPE *var" "TAILQ_HEAD *head" "HEADNAME" "TAILQ_ENTRY NAME" "TYPE *tmp" +.Fn TAILQ_INIT "TAILQ_HEAD *head" +.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_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_REMOVE "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME" +.Fn TAILQ_REPLACE "TAILQ_HEAD *head" "TYPE *elm" "TYPE *new" "TAILQ_ENTRY NAME" +.Fn TAILQ_CONCAT "TAILQ_HEAD *head1" "TAILQ_HEAD *head2" "TAILQ_ENTRY NAME" +.Pp +.Fn STAILQ_HEAD "HEADNAME" "TYPE" +.Fn STAILQ_HEAD_INITIALIZER "head" +.Fn STAILQ_ENTRY "TYPE" +.Ft TYPE * +.Fn STAILQ_FIRST "STAILQ_HEAD *head" +.Ft int +.Fn STAILQ_EMPTY "STAILQ_HEAD *head" +.Ft TYPE * +.Fn STAILQ_NEXT "TYPE *elm" "STAILQ_ENTRY NAME" +.Ft TYPE * +.Fn STAILQ_LAST "STAILQ_HEAD *head" "TYPE *elm" "STAILQ_ENTRY NAME" +.Fn STAILQ_FOREACH "TYPE *var" "STAILQ_HEAD *head" "STAILQ_ENTRY NAME" +.Fn STAILQ_FOREACH_SAFE "TYPE *var" "STAILQ_HEAD *head" "STAILQ_ENTRY NAME" "TYPE *tmp" +.Fn STAILQ_INIT "STAILQ_HEAD *head" +.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_INSERT_AFTER "STAILQ_HEAD *head" "TYPE *listelm" "TYPE *elm" "STAILQ_ENTRY NAME" +.Fn STAILQ_REMOVE_HEAD "STAILQ_HEAD *head" "STAILQ_ENTRY NAME" +.Fn STAILQ_REMOVE "STAILQ_HEAD *head" "TYPE *elm" "TYPE" "STAILQ_ENTRY NAME" +.Fn STAILQ_CONCAT "STAILQ_HEAD *head1" "STAILQ_HEAD *head2" +.Sh DESCRIPTION +These macros define and operate on five types of data structures: +singly-linked lists, simple queues, lists, tail queues, and singly-linked +tail queues. +All five 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 +Removal of any entry in the list. +.It +Forward traversal through the list. +.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. +.Pp +Simple 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 concatenated. +.El +However: +.Bl -enum -compact -offset indent +.It +Entries may not be added before any element in the list. +.It +All list insertions and removals must specify the head of the list. +.It +Each head entry requires two pointers rather than one. +.El +.Pp +Simple 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 and +support only the above functionality over singly-linked lists. +.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 concatenated. +.El +However: +.Bl -enum -compact -offset indent +.It +All list insertions and removals, except insertion before another element, 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 lists. +.El +.Pp +Circular 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. +.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 +The termination condition for traversal is more complex. +.It +Code size is about 40% greater and operations run about 45% slower +than lists. +.El +.Pp +In the macro definitions, +.Fa TYPE +is the name of a user defined structure, +that must contain a field of type +.Li SLIST_ENTRY , +.Li LIST_ENTRY , +.Li SIMPLEQ_ENTRY , +.Li TAILQ_ENTRY , +or +.Li STAILQ_ENTRY , +named +.Fa NAME . +The argument +.Fa HEADNAME +is the name of a user defined structure that must be declared +using the macros +.Li LIST_HEAD , +.Li SIMPLEQ_HEAD , +.Li SLIST_HEAD , +or +.Li TAILQ_HEAD . +See the examples below for further explanation of how these +macros are used. +.Ss Summary of Operations +The following table summarizes the supported macros for each type +of data structure. +.Pp +.TS +box tab(:); +l | c | c | c | c | c +l | c | c | c | c | c +l | c | c | c | c | c +l | c | c | c | c | c +l | c | c | c | c | c +l | c | c | c | c | c. +:SLIST:LIST:SIMPLEQ:TAILQ:STAILQ +_ +_FIRST:+:+:+:+:+ +_EMPTY:+:+:+:+:+ +_NEXT:+:+:+:+:+ +_PREV:-:-:-:+:- +_LAST:-:-:+:+:+ +_FOREACH:+:+:+:+:+ +_FOREACH_SAFE:+:+:+:+:+ +_FOREACH_REVERSE:-:-:-:+:- +_FOREACH_REVERSE_SAFE:-:-:-:+:- +_INSERT_HEAD:+:+:+:+:+ +_INSERT_AFTER:+:+:+:+:+ +_INSERT_BEFORE:-:+:-:+:- +_INSERT_TAIL:-:-:+:+:+ +_REMOVE:+:+:+:+:+ +_REMOVE_HEAD:+:-:+:-:+ +_REMOVE_AFTER:-:-:+:-:+ +_REPLACE:-:+:-:+:- +_CONCAT:-:-:+:+:+ +.TE +.Sh SINGLY-LINKED LISTS +A singly-linked list is headed by a structure defined by the +.Fn 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 +.Fn SLIST_HEAD_INITIALIZER +evaluates to an initializer for the list +.Fa head . +.Pp +The macro +.Fn SLIST_ENTRY +declares a structure that connects the elements in +the list. +.Pp +The macro +.Fn SLIST_FIRST +returns the first element in the list or NULL if the list is empty. +.Pp +The macro +.Fn SLIST_EMPTY +evaluates to true if there are no elements in the list. +.Pp +The macro +.Fn SLIST_NEXT +returns the next element in the list. +.Pp +.Fn SLIST_FOREACH +traverses the list referenced by +.Fa head +in the forward direction, assigning each element in +turn to +.Fa var . +.Pp +The SAFE version uses +.Fa tmp +to hold the next element, so +.Fa var +may be freed or removed from the list. +.Pp +The macro +.Fn SLIST_INIT +initializes the list referenced by +.Fa head . +.Pp +The macro +.Fn SLIST_INSERT_HEAD +inserts the new element +.Fa elm +at the head of the list. +.Pp +The macro +.Fn SLIST_INSERT_AFTER +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +The macro +.Fn SLIST_REMOVE +removes the element +.Fa elm +from the list. +.Pp +The macro +.Fn SLIST_REMOVE_HEAD +removes the first element 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 +.Fn SLIST_REMOVE +macro. +.Pp +The macro +.Fn SLIST_REMOVE_AFTER +removes the element after the one specified. +For optimum efficiency, +elements being removed after a specified one should explicitly use +this macro instead of the generic +.Fn SLIST_REMOVE +.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); + +SLIST_FOREACH(np, &head, entries) /* Forward traversal. */ + np-> ... + +while (!SLIST_EMPTY(&head)) { /* List Deletion. */ + n1 = SLIST_FIRST(&head); + SLIST_REMOVE_HEAD(&head, entries); + free(n1); +} +.Ed +.Sh LISTS +A list is headed by a structure defined by the +.Fn 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 +.Fn LIST_ENTRY +declares a structure that connects the elements in +the list. +.Pp +The macro +.Fn LIST_HEAD_INITIALIZER +provides a value which can be used to initialize a list head at +compile time, and is used at the point that the list head +variable is declared, like: +.Bd -literal -offset indent +struct HEADNAME head = LIST_HEAD_INITIALIZER(head); +.Ed +.Pp +The macro +.Fn LIST_FIRST +returns the first element of the list +.Fa head . +.Pp +The macro +.Fn LIST_EMPTY +returns true if the list +.Fa head +has no elements. +.Pp +The macro +.Fn LIST_NEXT +returns the element after the element +.Fa elm . +.Pp +The macro +.Fn LIST_FOREACH +traverses the list referenced by +.Fa head +in the forward direction, assigning each element in turn to +.Fa var . +.Pp +The SAFE version uses +.Fa tmp +to hold the next element, so +.Fa var +may be freed or removed from the list. +.Pp +The macro +.Fn LIST_INIT +initializes the list referenced by +.Fa head . +.Pp +The macro +.Fn LIST_INSERT_AFTER +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +The macro +.Fn LIST_INSERT_BEFORE +inserts the new element +.Fa elm +before the element +.Fa listelm . +.Pp +The macro +.Fn LIST_INSERT_HEAD +inserts the new element +.Fa elm +at the head of the list. +.Pp +The macro +.Fn 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. +.Pp +The macro +.Fn LIST_MOVE +moves the list headed by +.Fa head1 +onto the list headed by +.Fa head2 , +always making the former empty. +.Sh LIST EXAMPLE +.Bd -literal +LIST_HEAD(listhead, entry) head; +struct listhead *headp; /* List head. */ +struct entry { + ... + LIST_ENTRY(entry) entries; /* List. */ + ... +} *n1, *n2, *np; + +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); + +n2 = malloc(sizeof(struct entry)); /* Insert before. */ +LIST_INSERT_BEFORE(n1, n2, entries); + +LIST_FOREACH(np, &head, entries) /* Forward traversal. */ + np-> ... + +while (LIST_FIRST(&head) != NULL) /* Delete. */ + LIST_REMOVE(LIST_FIRST(&head), entries); +if (LIST_EMPTY(&head)) /* Test for emptiness. */ + printf("nothing to do\\n"); +.Ed +.Sh SIMPLE QUEUES +A simple queue is headed by a structure defined by the +.Fn SIMPLEQ_HEAD +macro. +This structure contains a pair of pointers, +one to the first element in the simple queue and the other to +the last element in the simple 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 queue after an existing element, +at the head of the queue, or at the end of the queue. +A +.Fa SIMPLEQ_HEAD +structure is declared as follows: +.Bd -literal -offset indent +SIMPLEQ_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 simple queue. +A pointer to the head of the simple 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 +.Fn SIMPLEQ_ENTRY +declares a structure that connects the elements in +the simple queue. +.Pp +The macro +.Fn SIMPLEQ_HEAD_INITIALIZER +provides a value which can be used to initialize a simple queue head at +compile time, and is used at the point that the simple queue head +variable is declared, like: +.Bd -literal -offset indent +struct HEADNAME head = SIMPLEQ_HEAD_INITIALIZER(head); +.Ed +.Pp +The macro +.Fn SIMPLEQ_FIRST +returns the first element of the simple queue +.Fa head . +.Pp +The macro +.Fn SIMPLEQ_EMPTY +returns true if the simple queue +.Fa head +has no elements. +.Pp +The macro +.Fn SIMPLEQ_NEXT +returns the element after the element +.Fa elm . +.Pp +The macro +.Fn SIMPLEQ_LAST +returns the last item on the simple queue. +If the simple queue is empty the return value is +.Dv NULL . +.Pp +The macro +.Fn SIMPLEQ_FOREACH +traverses the simple queue referenced by +.Fa head +in the forward direction, assigning each element +in turn to +.Fa var . +.Pp +The SAFE version uses +.Fa tmp +to hold the next element, so +.Fa var +may be freed or removed from the list. +.Pp +The macro +.Fn SIMPLEQ_INIT +initializes the simple queue referenced by +.Fa head . +.Pp +The macro +.Fn SIMPLEQ_INSERT_HEAD +inserts the new element +.Fa elm +at the head of the simple queue. +.Pp +The macro +.Fn SIMPLEQ_INSERT_TAIL +inserts the new element +.Fa elm +at the end of the simple queue. +.Pp +The macro +.Fn SIMPLEQ_INSERT_AFTER +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +The macro +.Fn SIMPLEQ_REMOVE_HEAD +removes the first element from the head of the simple queue. +For optimum efficiency, +elements being removed from the head of the queue should explicitly use +this macro instead of the generic +.Fn SIMPLEQ_REMOVE +macro. +.Pp +The macro +.Fn SIMPLEQ_REMOVE_AFTER +removes the element after the one specified from the simple queue. +For optimum efficiency, +elements being removed after specified elements should explicitly use +this macro instead of the generic +.Fn SIMPLEQ_REMOVE +macro. +.Pp +The macro +.Fn SIMPLEQ_REMOVE +removes +.Fa elm +from the simple queue. +.Pp +The macro +.Fn SIMPLEQ_CONCAT +concatenates the simple queue headed by +.Fa head2 +onto the end of the one headed by +.Fa head1 , +removing all entries from the former. +.Sh SIMPLE QUEUE EXAMPLE +.Bd -literal +SIMPLEQ_HEAD(simplehead, entry) head; +struct simplehead *headp; /* Simple queue head. */ +struct entry { + ... + SIMPLEQ_ENTRY(entry) entries; /* Simple queue. */ + ... +} *n1, *n2, *np; + +SIMPLEQ_INIT(&head); /* Initialize the queue. */ + +n1 = malloc(sizeof(struct entry)); /* Insert at the head. */ +SIMPLEQ_INSERT_HEAD(&head, n1, entries); + +n1 = malloc(sizeof(struct entry)); /* Insert at the tail. */ +SIMPLEQ_INSERT_TAIL(&head, n1, entries); + +n2 = malloc(sizeof(struct entry)); /* Insert after. */ +SIMPLEQ_INSERT_AFTER(&head, n1, n2, entries); + +SIMPLEQ_FOREACH(np, &head, entries) /* Forward traversal. */ + np-> ... + +while (SIMPLEQ_FIRST(&head) != NULL) /* Delete. */ + SIMPLEQ_REMOVE_HEAD(&head, entries); +if (SIMPLEQ_EMPTY(&head)) /* Test for emptiness. */ + printf("nothing to do\\n"); +.Ed +.Sh TAIL QUEUES +A tail queue is headed by a structure defined by the +.Fn 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 queue after an existing element, +before an existing element, at the head of the queue, or at the end +the 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 +.Fn TAILQ_ENTRY +declares a structure that connects the elements in +the tail queue. +.Pp +The macro +.Fn TAILQ_HEAD_INITIALIZER +provides a value which can be used to initialize a tail queue head at +compile time, and is used at the point that the tail queue head +variable is declared, like: +.Bd -literal -offset indent +struct HEADNAME head = TAILQ_HEAD_INITIALIZER(head); +.Ed +.Pp +The macro +.Fn TAILQ_FIRST +returns the first element of the tail queue +.Fa head . +.Pp +The macro +.Fn TAILQ_NEXT +returns the element after the element +.Fa elm . +.Pp +The macro +.Fn 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 +.Fn TAILQ_PREV +returns the previous item on the tail queue, from the one specified. +If the tail queue is empty the return value is +.Dv NULL . +.Pp +The macro +.Fn TAILQ_EMPTY +returns true if the tail queue +.Fa head +has no elements. +.Pp +The macros +.Fn TAILQ_FOREACH , +.Fn TAILQ_FOREACH_REVERSE , +.Fn TAILQ_FOREACH_SAFE , +and +.Fn TAILQ_FOREACH_REVERSE_SAFE +traverse the tail queue referenced by +.Fa head +in the forward or reverse direction, assigning each element in turn to +.Fa var . +.Pp +The SAFE versions use +.Fa tmp +to hold the next element, so +.Fa var +may be freed or removed from the list. +.Pp +The macro +.Fn TAILQ_INIT +initializes the tail queue referenced by +.Fa head . +.Pp +The macro +.Fn TAILQ_INSERT_HEAD +inserts the new element +.Fa elm +at the head of the tail queue. +.Pp +The macro +.Fn TAILQ_INSERT_TAIL +inserts the new element +.Fa elm +at the end of the tail queue. +.Pp +The macro +.Fn TAILQ_INSERT_AFTER +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +The macro +.Fn TAILQ_INSERT_BEFORE +inserts the new element +.Fa elm +before the element +.Fa listelm . +.Pp +The macro +.Fn TAILQ_REMOVE +removes the element +.Fa elm +from the tail queue. +.Pp +The macro +.Fn TAILQ_REPLACE +replaces the element +.Fa elm +with the +.Fa new +one specified in the tail queue. +.Pp +The macro +.Fn 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. +.Sh TAIL QUEUE EXAMPLE +.Bd -literal +TAILQ_HEAD(tailhead, entry) head; +struct tailhead *headp; /* Tail queue head. */ +struct entry { + ... + TAILQ_ENTRY(entry) entries; /* Tail queue. */ + ... +} *n1, *n2, *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); + +n2 = malloc(sizeof(struct entry)); /* Insert before. */ +TAILQ_INSERT_BEFORE(n1, n2, entries); + +TAILQ_FOREACH(np, &head, entries) /* Forward traversal. */ + np-> ... + /* Reverse traversal. */ +TAILQ_FOREACH_REVERSE(np, &head, tailhead, entries) + np-> ... + +while (TAILQ_FIRST(&head) != NULL) /* Delete. */ + TAILQ_REMOVE(&head, TAILQ_FIRST(&head), entries); +if (TAILQ_EMPTY(&head)) /* Test for emptiness. */ + printf("nothing to do\\n"); +.Ed +.Sh SINGLY LINKED TAIL QUEUES +The macros prefixed with +.Do Nm STAILQ_ Dc ( +.Fn STAILQ_HEAD , +.Fn STAILQ_HEAD_INITIALIZER , +.Fn STAILQ_ENTRY , +.Fn STAILQ_FOREACH , +.Fn STAILQ_FOREACH_SAFE , +.Fn STAILQ_FIRST , +.Fn STAILQ_EMPTY , +.Fn STAILQ_NEXT , +.Fn STAILQ_LAST , +.Fn STAILQ_INIT , +.Fn STAILQ_INSERT_HEAD , +.Fn STAILQ_INSERT_TAIL , +.Fn STAILQ_INSERT_AFTER , +.Fn STAILQ_REMOVE_HEAD , +.Fn STAILQ_REMOVE , +and +.Fn STAILQ_CONCAT ) +are functionally identical to these simple queue functions, +and are provided for compatibility with +.Fx . +.Sh NOTES +Some of these macros or functions perform no error checking, +and invalid usage leads to undefined behaviour. +In the case of macros or functions that expect their arguments +to be elements that are present in the list or queue, passing an element +that is not present is invalid. +.Sh HISTORY +The +.Nm queue +functions first appeared in +.Bx 4.4 . +The +.Nm SIMPLEQ +functions first appeared in +.Nx 1.2 . +The +.Nm SLIST +and +.Nm STAILQ +functions first appeared in +.Fx 2.1.5 . +.Pp +The +.Nm CIRCLEQ +functions first appeared in +.Bx 4.4 +and were deprecated in +.Nx 7 +and removed in +.Nx 10 +due to the pointer aliasing violations. diff --git a/static/netbsd/man3/rbtree.3 b/static/netbsd/man3/rbtree.3 new file mode 100644 index 00000000..411d4356 --- /dev/null +++ b/static/netbsd/man3/rbtree.3 @@ -0,0 +1,319 @@ +.\" $NetBSD: rbtree.3,v 1.14 2025/10/22 12:34:00 roy Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Matt Thomas, Niels Provos, and David Young. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 22, 2025 +.Dt RBTREE 3 +.Os +.Sh NAME +.Nm rbtree +.Nd red-black tree +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/rbtree.h +.Ft void +.Fn rb_tree_init "rb_tree_t *rbt" "const rb_tree_ops_t *ops" +.Ft void * +.Fn rb_tree_insert_node "rb_tree_t *rbt" "void *rb" +.Ft void +.Fn rb_tree_remove_node "rb_tree_t *rbt" "void *rb" +.Ft void * +.Fn rb_tree_find_node "rb_tree_t *rbt" "const void *key" +.Ft void * +.Fn rb_tree_find_node_geq "rb_tree_t *rbt" "const void *key" +.Ft void * +.Fn rb_tree_find_node_leq "rb_tree_t *rbt" "const void *key" +.Ft void * +.Fn rb_tree_iterate "rb_tree_t *rbt" "void *rb" "unsigned int direction" +.Ft void * +.Fn RB_TREE_MIN "rb_tree_t *rbt" +.Ft void * +.Fn RB_TREE_MAX "rb_tree_t *rbt" +.Fn RB_TREE_NEXT "rb_tree_t *rbt" "void *rb" +.Fn RB_TREE_PREV "rb_tree_t *rbt" "void *rb" +.Fn RB_TREE_FOREACH "void *rb" "rb_tree_t *rbt" +.Fn RB_TREE_FOREACH_SAFE "void *rb" "rb_tree_t *rbt" "void *tmp" +.Fn RB_TREE_FOREACH_REVERSE "void *rb" "rb_tree_t *rbt" +.Fn RB_TREE_FOREACH_REVERSE_SAFE "void *rb" "rb_tree_t *rbt" "void *tmp" +.Sh DESCRIPTION +.Nm +provides red-black trees. +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 O(lg n). +The maximum height of a red-black tree is 2lg (n+1). +.Sh TYPES +.Bl -tag -width compact +.It Vt rb_tree_t +A red-black tree. +.It Vt typedef signed int \ +(* rbto_compare_nodes_fn)(void *context, const void *node1, const void *node2); +The node-comparison function. +Defines an ordering on nodes. +Returns a negative value if the first node +.Ar node1 +precedes the second node +.Ar node2 . +Returns a positive value if the first node +.Ar node1 +follows the second node +.Ar node2 . +Returns 0 if the first node +.Ar node1 +and the second node +.Ar node2 +are identical according to the ordering. +.It Vt typedef signed int \ +(* rbto_compare_key_fn)(void *context, const void *node, const void *key); +The node-key comparison function. +Defines the order of nodes and keys. +Returns a negative value if the node +.Ar node +precedes the key +.Ar key . +Returns a positive value if the node +.Ar node +follows the key +.Ar key . +Returns 0 if the node +.Ar node +is identical to the key +.Ar key +according to the ordering. +.It Vt rb_tree_ops_t +Defines the function for comparing two nodes in the same tree, +the function for comparing a node in the tree with a key, +the offset of member +.Vt rb_node_t +within the node type, +and the opaque context pointer passed to the comparison functions. +Members of +.Vt rb_tree_ops_t +are +.Bd -literal + rbto_compare_nodes_fn rbto_compare_nodes; + rbto_compare_key_fn rbto_compare_key; + size_t rbto_node_offset; + void *rbto_context; +.Ed +.It Vt rb_node_t +A node in a red-black tree has this structure as a member. +The offset of the +.Vt rb_node_t +member in the caller's node structure should be provided as +.Va rbto_node_offset . +(None of the functions in the +.Nm +interface are meant to take pointers directly to the +.Vt rb_node_t +member.) +.El +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn rb_tree_init "rbt" "ops" +Initialize the red-black tree +.Fa rbt . +Let the comparison functions given by +.Fa ops +define the order of nodes in the tree for +the purposes of insertion, search, and iteration. +.Fn rb_tree_init +always succeeds. +.It Fn rb_tree_insert_node "rbt" "rb" +Insert the node +.Fa rb +into the tree +.Fa rbt . +Return inserted node on success, +already existing node on failure. +.It Fn rb_tree_remove_node "rbt" "rb" +Remove the node +.Fa rb +from the tree +.Fa rbt . +.It Fn rb_tree_find_node "rbt" "key" +Search the tree +.Fa rbt +for a node exactly matching +.Fa key . +If no such node is in the tree, return +.Dv NULL . +Otherwise, return the matching node. +.It Fn rb_tree_find_node_geq "rbt" "key" +Search the tree +.Fa rbt +for a node that exactly matches +.Fa key +and return it. +If no such node is present, return the first node following +.Fa key +or, if no such node is in the tree, return +.Dv NULL . +.It Fn rb_tree_find_node_leq "rbt" "key" +Search the tree +.Fa rbt +for a node that exactly matches +.Fa key +and return it. +If no such node is present, return the first node preceding +.Fa key +or, if no such node is in the tree, return +.Dv NULL . +.It Fn rb_tree_iterate "rbt" "rb" "direction" +If +.Fa direction +is +.Dv RB_DIR_LEFT , +return the node in the tree +.Fa rbt +immediately preceding the node +.Fa rb +or, if +.Fa rb +is +.Dv NULL , +return the first node in +.Fa rbt +or, if the tree is empty, return +.Dv NULL . +.Pp +If +.Fa direction +is +.Dv RB_DIR_RIGHT , +return the node in the tree +.Fa rbt +immediately following the node +.Fa rb +or, if +.Fa rb +is +.Dv NULL , +return the last node in +.Fa rbt +or, if the tree is empty, return +.Dv NULL . +.It Fn RB_TREE_MIN "rbt" +Return the first node in +.Fa rbt , +i.e. the node with the least key, or +.Dv NULL +if +.Fa rbt +is empty. +.It Fn RB_TREE_MAX "rbt" +Return the last node in +.Fa rbt , +i.e. the node with the greatest key, or +.Dv NULL +if +.Fa rbt +is empty. +.It Fn RB_TREE_NEXT "rbt" "rb" +Return the next node in +.Fa rbt , +or +.Dv NULL +if there is none. +.It Fn RB_TREE_PREV "rbt" "rb" +Return the previous node in +.Fa rbt , +or +.Dv NULL +if there is none. +.It Fn RB_TREE_FOREACH "rb" "rbt" +.Nm RB_TREE_FOREACH +is a macro to be used in the place of a +.Dv for +header preceding a statement to traverse the nodes in +.Fa rbt +from least to greatest, assigning +.Fa rb +to each node in turn and executing the statement. +.It Fn RB_TREE_FOREACH_SAFE "rb" "rbt" "tmp" +Allows both the removal of +.Fa rb +as well as freeing it from within the loop safely without interfering +with the traversal. +.It Fn RB_TREE_FOREACH_REVERSE "rb" "rbt" +.Nm RB_TREE_FOREACH_REVERSE +is a macro to be used in the place of a +.Dv for +header preceding a statement to traverse the nodes in +.Fa rbt +from greatest to least, assigning +.Fa rb +to each node in turn and executing the statement. +.It Fn RB_TREE_FOREACH_REVERSE_SAFE "rb" "rbt" "tmp" +Allows both the removal of +.Fa rb +as well as freeing it from within the loop safely without interfering +with the traversal. +.El +.Sh CODE REFERENCES +The +.Nm +interface is implemented in +.Pa common/lib/libc/gen/rbtree.c . +.\" .Sh EXAMPLES +.\" +.\" XXX: Should contain some examples. +.\" +.Sh SEE ALSO +.Xr queue 3 , +.Xr tree 3 +.Sh HISTORY +The +.Nm +interface first appeared in +.Nx 6.0 . +.Sh AUTHORS +.An Matt Thomas Aq Mt matt@NetBSD.org +wrote +.Nm . +.Pp +.An Niels Provos Aq Mt provos@citi.umich.edu +wrote the +.Xr tree 3 +manual page. +Portions of this page derive from that page. +.\" .Sh CAVEATS +.\" .Sh BUGS +.\" .Sh SECURITY CONSIDERATIONS diff --git a/static/netbsd/man3/sigevent.3 b/static/netbsd/man3/sigevent.3 new file mode 100644 index 00000000..bc6265d1 --- /dev/null +++ b/static/netbsd/man3/sigevent.3 @@ -0,0 +1,180 @@ +.\" $NetBSD: sigevent.3,v 1.8 2010/06/24 04:21:58 jruoho Exp $ +.\" +.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@iki.fi> +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 June 24, 2010 +.Dt SIGEVENT 3 +.Os +.Sh NAME +.Nm sigevent +.Nd signal event structure +.Sh SYNOPSIS +.In sys/signal.h +.Sh DESCRIPTION +The +.St -p1003.1-2004 +standard extends traditional +.Tn UNIX +signal semantics by providing facilities +for realtime signal generation and delivery. +.Pp +.\" +.\" XXX: Remove once these are fixed. +.\" +.Bf -symbolic +Please note that this manual describes an interface that +is not yet fully functional in +.Nx : +neither realtime signals nor SIGEV_THREAD +are currently supported. +.Ef +.Pp +Realtime functions that can generate realtime signals include: +.Bl -enum -offset 3n +.It +Completion of asynchronous +.Tn I/O ; +see +.Xr aio 3 . +.It +Expiration of per-process timers; see +.Xr timer_create 2 . +.It +Arrival of a message to an empty message queue; see +.Xr mq_notify 3 . +.El +.Pp +The +.In sys/signal.h +header, included by +.In signal.h , +defines a +.Va sigevent +structure, which is the cornerstone in +asynchronous delivery of realtime signals. +This structure is defined as: +.Bd -literal -offset indent +struct sigevent { + int sigev_notify; + int sigev_signo; + union sigval sigev_value; + void (*sigev_notify_function)(union sigval); + void *sigev_notify_attributes; +}; +.Ed +.Pp +The included union is further defined in +.In siginfo.h +as: +.Bd -literal -offset indent +typedef union sigval { + int sival_int; + void *sival_ptr; +} sigval_t; +.Ed +.Pp +The +.Va sigev_notify +integer defines the action taken when +a notification such as timer expiration occurs. +The possiblue values are: +.Bl -tag -width "SIGEV_THREAD " -offset 2n +.It Dv SIGEV_NONE +This constant specifies a +.Dq null +handler: when a notification arrives, nothing happens. +.It Dv SIGEV_SIGNAL +The +.Dv SIGEV_SIGNAL +constant specifies that notifications are delivered by signals. +When a notification arrives, the kernel sends the signal specified in +.Va sigev_signo . +.Pp +In the signal handler the +.Sq si_value +of +.Va siginfo_t +is set to the value specified by the +.Va sigev_value . +In another words, the +.Va sigev_value +member is an application-defined value to be passed to +a particular signal handler at the time of signal delivery. +Depending whether the specified value is an integer or a pointer, the +delivered value can be either +.Va sigval_intr +or +.Va sigval_ptr . +.It Dv SIGEV_THREAD +This constant specifies a thread-driven notification mechanism. +When a notification occurs, the kernel creates a new thread that starts +executing the function specified in the function pointer +.Va sigev_notify_function . +The single argument passed to the function is specified in +.Va sigev_value . +.Pp +If +.Va sigev_notify_attributes +is not +.Dv NULL , +the provided attribute specifies the behavior of the thread; see +.Xr pthread_attr 3 . +(Note that although a pointer to void is specified for +.Va sigev_notify_attributes , +the type is +.Va pthread_attr_t +in practice.) +.Pp +The threads are created as detached, +or in an unspecified way if +.Xr pthread_attr_setdetachstate 3 +is used with +.Va sigev_notify_attributes +to set +.Dv PTHREAD_CREATE_JOINABLE . +It is not valid to call +.Xr pthread_join 3 +in either case. +Hence, it is impossible to determine the lifetime of the created thread. +This in turn means that it is neither possible to recover the memory nor +the address of the memory possibly dedicated as thread stack via +.Fn pthread_attr_setstack +or +.Fn pthread_attr_setstackaddr . +.El +.\" +.\" .Sh EXAMPLES +.\" +.\" XXX: Add one. +.\" +.Sh SEE ALSO +.Xr siginfo 2 , +.Xr timer_create 2 , +.Xr aio 3 , +.Xr mq 3 +.Sh HISTORY +The +.Va sigevent +structure first appeared in +.Nx 1.6 . diff --git a/static/netbsd/man3/stdarg.3 b/static/netbsd/man3/stdarg.3 new file mode 100644 index 00000000..d722d11b --- /dev/null +++ b/static/netbsd/man3/stdarg.3 @@ -0,0 +1,269 @@ +.\" $NetBSD: stdarg.3,v 1.21 2015/06/15 02:06:18 dholland Exp $ +.\" +.\" 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. +.\" +.\" @(#)stdarg.3 8.1 (Berkeley) 6/5/93 +.\" +.Dd June 14, 2015 +.Dt STDARG 3 +.Os +.Sh NAME +.Nm stdarg , +.Nm va_arg , +.Nm va_copy , +.Nm va_end , +.Nm va_start +.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 three 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_end , +and, optionally, +.Fn va_copy . +.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_start +macro returns no value. +.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 . +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 +If the type in question is one that gets promoted, the promoted type +should be used as the argument to +.Fn va_arg . +The following describes which types are promoted (and to what): +.Bl -dash -compact +.It +.Va short +is promoted to +.Va int +.It +.Va float +is promoted to +.Va double +.It +.Va char +is promoted to +.Va int +.El +.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 makes +.Fa dest +a copy of +.Fa src +as if the +.Fn va_start +macro had been applied to it followed by the same sequence of uses of the +.Fn va_arg +macro as had previously been used to reach the present state of +.Fa src . +.Pp +The +.Fn va_copy +macro returns no value. +.Pp +The +.Fn va_end +macro handles a normal return from the function whose variable argument +list was initialized by +.Fn va_start +or +.Fn va_copy . +.Pp +The +.Fn va_end +macro returns no value. +.Sh EXAMPLES +The function +.Fn 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, c; + char *s; + double f; + + 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 */ + c = va_arg(ap, int); /* promoted */ + printf("char %c\en", c); + break; + case 'f': /* float */ + f = va_arg(ap, double); /* promoted */ + printf("float %f\en", f); + } + va_end(ap); +} +.Ed +.Sh COMPATIBILITY +These macros are +.Em not +compatible with the historic +.In varargs.h +macros they replaced. +Any remaining code using the pre-C89 +.In varargs.h +interface should be updated. +.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 stdarg +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 stdarg +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/netbsd/man3/stdbool.3 b/static/netbsd/man3/stdbool.3 new file mode 100644 index 00000000..99f7160c --- /dev/null +++ b/static/netbsd/man3/stdbool.3 @@ -0,0 +1,78 @@ +.\" $NetBSD: stdbool.3,v 1.2 2010/05/14 02:45:39 joerg Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 21, 2010 +.Dt STDBOOL 3 +.Os +.Sh NAME +.Nm stdbool +.Nd standard boolean types +.Sh SYNOPSIS +.In stdbool.h +.Sh DESCRIPTION +The +.In stdbool.h +header defines four macros: +.Bl -enum -offset 4n +.It +.Vt bool , +which expands to +.Vt _Bool ; +.It +.Vt true , +which expands to the integer constant 1; +.It +.Vt false , +which expands to the integer constant 0; and +.It +.Vt __bool_true_false_are_defined , +which expands to the constant 1. +.El +.Pp +The ability to undefine and redefine the macros +.Vt bool , +.Vt true , +and +.Vt false +is an obsolescent feature that may +be withdrawn in a future version of a standard. +.Sh SEE ALSO +.Xr stdint 3 +.Sh STANDARDS +The +.In stdbool.h +header conforms to +.St -isoC-99 +and +.St -p1003.1-2001 . +.Sh HISTORY +The +.In stdbool.h +header was first introduced in +.Nx 1.6 . diff --git a/static/netbsd/man3/stddef.3 b/static/netbsd/man3/stddef.3 new file mode 100644 index 00000000..3c913b50 --- /dev/null +++ b/static/netbsd/man3/stddef.3 @@ -0,0 +1,93 @@ +.\" $NetBSD: stddef.3,v 1.8 2011/04/10 10:02:34 jruoho Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 10, 2011 +.Dt STDDEF 3 +.Os +.Sh NAME +.Nm stddef +.Nd standard type definitions +.Sh SYNOPSIS +.In stddef.h +.Sh DESCRIPTION +The +.In stddef.h +header defines the following types and macros: +.Bl -enum -offset 4n +.It +.Vt ptrdiff_t , +a signed integer type of the result of subtracting two pointers; +.It +.Vt size_t , +an unsigned integer type of the result of the +.Fn sizeof +operator; +.It +.Vt wchar_t , +an integer type whose range of values can represent distinct wide-character +codes for all members of the largest character set specified among the +supported locales: the null character has the code value 0 and each member +of the character set has a code value equal to its value when used +as the lone character in an integer character constant; +.It +.Dv NULL , +which expands to an implementation-defined null pointer constant; and +.It +.Fn offsetof , +a macro that expands to an integer constant as described in +.Xr offsetof 3 . +.El +.Pp +Some of the described types and macros may appear also in other headers. +.Sh SEE ALSO +.Xr offsetof 3 , +.Xr stdlib 3 , +.Xr unistd 3 +.Sh STANDARDS +As described here, the +.In stddef.h +header conforms to +.St -isoC-99 +and +.St -p1003.1-2001 . +Some of the types and macros conform to earlier standards such as +.St -ansiC . +.Sh HISTORY +In the current form the +.In stddef.h +header was introduced in +.Nx 0.8 , +the first official release of +.Nx . +Some definitions such as +.Dv NULL +were first introduced already in the +.In nsys/param.h +header of +.At v4 . diff --git a/static/netbsd/man3/stdint.3 b/static/netbsd/man3/stdint.3 new file mode 100644 index 00000000..3d755083 --- /dev/null +++ b/static/netbsd/man3/stdint.3 @@ -0,0 +1,139 @@ +.\" $NetBSD: stdint.3,v 1.6 2011/08/09 18:11:37 jruoho Exp $ +.\" +.\" Copyright (c) 2002 Mike Barcroft <mike@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD: src/share/man/man7/stdint.7,v 1.5 2003/09/08 19:57:21 ru Exp $ +.\" +.Dd August 9, 2011 +.Dt STDINT 3 +.Os +.Sh NAME +.Nm stdint +.Nd standard integer types +.Sh SYNOPSIS +.In stdint.h +.Sh DESCRIPTION +The +.In stdint.h +header provides source-portable integer types of a specific +size, smallest memory footprint with a minimum size, fastest +access speed with a minimum size, largest integer size, and +those capable of storing pointers. +.Pp +The types +.Vt int8_t , +.Vt int16_t , +.Vt int32_t , +and +.Vt int64_t +provide a signed integer type of width 8, 16, 32, or 64 bits, respectively. +The types +.Vt uint8_t , +.Vt uint16_t , +.Vt uint32_t , +and +.Vt uint64_t +provide an unsigned integer type of width 8, 16, 32, or 64 bits, respectively. +These integer types should be used when a specific size is required. +.Pp +The types +.Vt int_fast8_t , +.Vt int_fast16_t , +.Vt int_fast32_t , +and +.Vt int_fast64_t +provide the fastest signed integer type with a width +of at least 8, 16, 32, or 64 bits, respectively. +The types +.Vt uint_fast8_t , +.Vt uint_fast16_t , +.Vt uint_fast32_t , +and +.Vt uint_fast64_t +provide the fastest unsigned integer type with a width +of at least 8, 16, 32, or 64 bits, respectively. +These types should be used when access speed is +paramount, and when a specific size is not required. +.Pp +The types +.Vt int_least8_t , +.Vt int_least16_t , +.Vt int_least32_t , +and +.Vt int_least64_t +provide the smallest memory footprint signed integer type with +a width of at least 8, 16, 32, or 64 bits, respectively. +The types +.Vt uint_least8_t , +.Vt uint_least16_t , +.Vt uint_least32_t , +and +.Vt uint_least64_t +provide the smallest memory footprint unsigned integer type with +a width of at least 8, 16, 32, or 64 bits, respectively. +These types should be used when memory storage is of +concern, and when a specific size is not required. +.Pp +The type +.Vt intmax_t +provides a signed integer type large +enough to hold any other signed integer. +The type +.Vt uintmax_t +provides an unsigned integer type large +enough to hold any other unsigned integer. +These types are generally the largest signed and unsigned +integer types available on a specific architecture. +.Pp +The type +.Vt intptr_t +provides a signed integer type with the ability to hold a pointer to +.Vt void , +that can later be converted back to a pointer to +.Vt void . +.Pp +The type +.Vt uintptr_t +provides an unsigned integer type with the ability to hold a pointer to +.Vt void , +that can later be converted back to a pointer to +.Vt void . +.Sh SEE ALSO +.Xr inttypes 3 , +.Xr limits 3 , +.Xr stdbool 3 , +.Xr unistd 3 +.Sh STANDARDS +The +.In stdint.h +header conforms to +.St -isoC-99 +and +.St -p1003.1-2001 . +.Sh HISTORY +The +.In stdint.h +header was first introduced in +.Nx 1.6 . diff --git a/static/netbsd/man3/stdlib.3 b/static/netbsd/man3/stdlib.3 new file mode 100644 index 00000000..9ca9e072 --- /dev/null +++ b/static/netbsd/man3/stdlib.3 @@ -0,0 +1,110 @@ +.\" $NetBSD: stdlib.3,v 1.3 2011/04/10 10:02:34 jruoho Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 10, 2011 +.Dt STDLIB 3 +.Os +.Sh NAME +.Nm stdlib +.Nd standard library definitions +.Sh SYNOPSIS +.In stdlib.h +.Sh DESCRIPTION +The +.In stdlib.h +header defines the following types and macros: +.Bl -enum -offset 4n +.It +.Dv NULL +- an implementation-defined null pointer constant; +.It +.Vt size_t +and +.Vt wchar_t +- integer types described in +.Xr stddef 3 ; +.It +.Vt div_t , +.Vt ldiv_t , +and +.Vt lldiv_t +- structures that are returned by the +.Xr div 3 , +.Xr ldiv 3 , +and +.Xr lldiv 3 +functions, respectively; +.It +.Dv RAND_MAX +- a macro which expands to an integer constant +that is the maximum value returned by the +.Xr rand 3 +function; +.It +.Dv MB_CUR_MAX +- an integer expression of type +.Vt size_t +whose value is the maximum number of bytes in a +character specified by the current locale; and +.It +.Dv EXIT_SUCCESS +and +.Dv EXIT_FAILURE +- macros which expand to integer constants +suitable for use as an argument to the +.Xr exit 3 +function. +.El +.Pp +The +.In stdlib.h +header also prototypes several important functions such as +.Xr abort 3 , +.Xr atoi 3 , +.Xr bsearch 3 , +.Xr free 3 , +.Xr malloc 3 , +and +.Xr strtol 3 . +.Sh SEE ALSO +.Xr stddef 3 , +.Xr types 3 , +.Xr unistd 3 +.Sh STANDARDS +As described here, the +.In stdlib.h +header conforms to +.St -isoC-99 +and +.St -p1003.1-2001 . +.Sh HISTORY +In the current form the +.In stdlib.h +header was introduced in +.Nx 0.8 . diff --git a/static/netbsd/man3/sysexits.3 b/static/netbsd/man3/sysexits.3 new file mode 100644 index 00000000..0c324be5 --- /dev/null +++ b/static/netbsd/man3/sysexits.3 @@ -0,0 +1,152 @@ +.\" $NetBSD: sysexits.3,v 1.6 2011/04/08 10:14:24 jruoho Exp $ +.\" +.\" 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. +.\" +.\" $FreeBSD: src/share/man/man3/sysexits.3,v 1.16 2005/06/30 13:13:49 hmp Exp $ +.\" +.\" " +.Dd March 25, 2010 +.Dt SYSEXITS 3 +.Os +.Sh NAME +.Nm sysexits +.Nd preferable exit codes for programs +.Sh SYNOPSIS +.In sysexits.h +.Sh DESCRIPTION +It is not a good practice to call +.Xr exit 3 +with arbitrary values to indicate a failure condition when ending a program. +In addition to the two standard constants in +.In stdlib.h , +.Dv EXIT_SUCCESS +and +.Dv EXIT_FAILURE , +the header +.In sysexits.h +defines few exit codes that can be used as a parameter to the +.Xr exit 3 +function. +By using these constants the caller of the process can get a rough +estimation about the failure class without looking up the source code. +.Pp +The successful exit is always indicated by a status of 0, or +.Dv EX_OK . +Error numbers begin at +.Dv 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 Dv 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 Dv 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 Dv 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 Dv EX_NOUSER Pq 67 +The user specified did not exist. +This might be used for mail +addresses or remote logins. +.It Dv EX_NOHOST Pq 68 +The host specified did not exist. +This is used in mail addresses or +network requests. +.It Dv 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 Dv EX_SOFTWARE Pq 70 +An internal software error has been detected. +This should be limited +to non-operating system related errors as possible. +.It Dv 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 Dv EX_OSFILE Pq 72 +Some system file (e.g., +.Pa /etc/passwd , +.Pa /var/run/utmp , +etc.) does not exist, cannot be opened, or has some sort of error +(e.g., syntax error). +.It Dv EX_CANTCREAT Pq 73 +A (user specified) output file cannot be created. +.It Dv EX_IOERR Pq 74 +An error occurred while doing I/O on some file. +.It Dv 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 Dv EX_PROTOCOL Pq 76 +The remote system returned something that was +.Dq not possible +during a protocol exchange. +.It Dv 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 +.Dv EX_NOINPUT +or +.Dv EX_CANTCREAT , +but rather for higher level permissions. +.It Dv 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 stdlib 3 +.Sh HISTORY +The +.In sysexits.h +header appeared somewhere after +.Bx 4.3 . +The manual page for it appeared in +.Nx 4.0 . +.Sh AUTHORS +This manual page was written by +.An J\(:org Wunsch +after the comments in +.In sysexits.h . +.Sh BUGS +The choice of an appropriate exit value is often ambiguous. diff --git a/static/netbsd/man3/tgmath.3 b/static/netbsd/man3/tgmath.3 new file mode 100644 index 00000000..299a955a --- /dev/null +++ b/static/netbsd/man3/tgmath.3 @@ -0,0 +1,154 @@ +.\" $NetBSD: tgmath.3,v 1.9 2014/03/18 18:20:39 riastradh Exp $ +.\" +.\" 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. +.\" +.\" $FreeBSD: src/share/man/man3/tgmath.3,v 1.3 2007/12/15 02:40:10 das Exp $ +.\" +.Dd December 14, 2010 +.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 \ +"COMPLEX FUNCTION" "COMPLEX FUNCTION" "COMPLEX FUNCTION" +.It Sy Macro Ta Sy Real function Ta Sy Complex function +.It Fn acos Ta Xr acos 3 Ta Xr cacos 3 +.It Fn asin Ta Xr asin 3 Ta Xr casin 3 +.It Fn atan Ta Xr atan 3 Ta Xr catan 3 +.It Fn acosh Ta Xr acosh 3 Ta Xr cacosh 3 +.It Fn asinh Ta Xr asinh 3 Ta Xr casinh 3 +.It Fn atanh Ta Xr atanh 3 Ta Xr catanh 3 +.It Fn cos Ta Xr cos 3 Ta Xr ccos 3 +.It Fn sin Ta Xr sin 3 Ta Xr csin 3 +.It Fn tan Ta Xr tan 3 Ta Xr ctan 3 +.It Fn cosh Ta Xr cosh 3 Ta Xr ccosh 3 +.It Fn sinh Ta Xr sinh 3 Ta Xr csinh 3 +.It Fn tanh Ta Xr tanh 3 Ta Xr ctanh 3 +.It Fn exp Ta Xr exp 3 Ta Xr cexp 3 +.It Fn log Ta Xr log 3 Ta Xr clog 3 +.It Fn pow Ta Xr pow 3 Ta Xr cpow 3 +.It Fn sqrt Ta Xr sqrt 3 Ta Xr csqrt 3 +.It Fn fabs Ta Xr fabs 3 Ta Xr cabs 3 +.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" +.It Xr atan2 3 Ta Fn fma Ta Fn llround Ta Xr remainder 3 +.It Xr cbrt 3 Ta Xr fmax 3 Ta Xr log10 3 Ta Fn remquo +.It Xr ceil 3 Ta Xr fmin 3 Ta Xr log1p 3 Ta Xr rint 3 +.It Xr copysign 3 Ta Xr fmod 3 Ta Xr log2 3 Ta Xr round 3 +.It Xr erf 3 Ta Xr frexp 3 Ta Xr logb 3 Ta Xr scalbn 3 +.It Xr erfc 3 Ta Xr hypot 3 Ta Xr lrint 3 Ta Fn tgamma +.It Xr exp2 3 Ta Xr ilogb 3 Ta Fn lround Ta Xr trunc 3 +.It Xr expm1 3 Ta Xr ldexp 3 Ta Xr nextafter 3 +.It Xr fdim 3 Ta Xr lgamma 3 Ta +.It Xr floor 3 Ta Xr llrint 3 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 Xr carg 3 Ta Xr cimag 3 Ta Xr conj 3 Ta Fn cproj Ta Xr creal 3 +.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 AUTHORS +.An Matt Thomas Aq Mt matt@3am-software.com +.Sh BUGS +The header +.In tgmath.h +cannot be implemented with strictly conforming C code and needs +special compiler support. +The current implementation only works for +.Tn GCC . +.Pp +Many of the functions mentioned here are not prototyped in +.In math.h +or +.In complex.h +as they are not yet implemented. diff --git a/static/netbsd/man3/timeradd.3 b/static/netbsd/man3/timeradd.3 new file mode 100644 index 00000000..d64a9cdf --- /dev/null +++ b/static/netbsd/man3/timeradd.3 @@ -0,0 +1,144 @@ +.\" $NetBSD: timeradd.3,v 1.10 2021/02/23 16:47:04 rillig Exp $ +.\" +.\" Copyright (c) 2009 Jukka Ruohonen <jruohonen@iki.fi> +.\" 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. +.\" +.\" $FreeBSD: src/share/man/man3/timeradd.3,v 1.3 2003/09/08 19:57:19 ru Exp $ +.\" +.Dd June 7, 2010 +.Dt TIMERADD 3 +.Os +.Sh NAME +.Nm timeradd +.Nd operations on time structure +.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 *tv" +.Ft int +.Fn timerisset "struct timeval *tv" +.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 "const struct timespec *a" "const struct timespec *b" CMP +.Sh DESCRIPTION +These macros are provided for manipulating the +.Fa timeval +and +.Fa timespec +structures described in +.Xr timeval 3 . +.Pp +The +.Fn timeradd +and +.Fn timespecadd +macros add the time information stored in +.Fa a +to +.Fa b , +storing the result in +.Fa res . +With +.Fn timeradd +the results are simplified such that the value of +.Fa res->tv_usec +is always less than 1,000,000 (1 second). +With +.Fn timespecadd +the +.Fa res->tv_nsec +member of +.Fa struct timespec +is always less than 1,000,000,000. +.Pp +The +.Fn timersub +and +.Fn timespecsub +macros subtract the time information stored in +.Fa b +from +.Fa a +and store the resulting structure +in +.Fa res . +.Pp +The +.Fn timerclear +and +.Fn timespecclear +macros initialize the structures +to midnight (0 hour) January 1st, 1970 (the Epoch). +In other words, they set the members of the structure to zero. +.Pp +The +.Fn timerisset +and +.Fn timespecisset +macros return true if the input structure +is set to any time value other than the Epoch. +.Pp +The +.Fn timercmp +and +.Fn timespeccmp +macros compare +.Fa a +to +.Fa b +using the comparison operator given in +.Fa CMP . +The result of the comparison is returned. +.Sh SEE ALSO +.Xr timeval 3 +.Sh HISTORY +The +.Fn timeradd +family of macros first appeared in +.Nx 1.1 . +These were later ported to +.Fx 2.2.6 . +The +.Fn timespec +family of macros first appeared in +.Nx 1.2 . diff --git a/static/netbsd/man3/timeval.3 b/static/netbsd/man3/timeval.3 new file mode 100644 index 00000000..4817faf9 --- /dev/null +++ b/static/netbsd/man3/timeval.3 @@ -0,0 +1,189 @@ +.\" $NetBSD: timeval.3,v 1.12 2011/04/12 08:39:26 jruoho Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 12, 2011 +.Dt TIMEVAL 3 +.Os +.Sh NAME +.Nm timeval , +.Nm timespec , +.Nm itimerval , +.Nm itimerspec , +.Nm bintime +.Nd time structures +.Sh SYNOPSIS +.In sys/time.h +.Ft void +.Fn TIMEVAL_TO_TIMESPEC "struct timeval *tv" "struct timespec *ts" +.Ft void +.Fn TIMESPEC_TO_TIMEVAL "struct timeval *tv" "struct timespec *ts" +.Sh DESCRIPTION +The +.In sys/time.h +header, included by +.In time.h , +defines various structures related to time and timers. +.Bl -enum -offset 1n +.It +The following structure is used by +.Xr gettimeofday 2 , +among others: +.Bd -literal -offset indent +struct timeval { + time_t tv_sec; + suseconds_t tv_usec; +}; +.Ed +.Pp +The +.Va tv_sec +member represents the elapsed time, in whole seconds. +The +.Va tv_usec +member captures rest of the elapsed time, +represented as the number of microseconds. +.It +The following structure is used by +.Xr nanosleep 2 , +among others: +.Bd -literal -offset indent +struct timespec { + time_t tv_sec; + long tv_nsec; +}; +.Ed +.Pp +The +.Va tv_sec +member is again the elapsed time in whole seconds. +The +.Va tv_nsec +member represents the rest of the elapsed time in nanoseconds. +.Pp +A microsecond is equal to one millionth of a second, +1000 nanoseconds, or 1/1000 milliseconds. +To ease the conversions, the macros +.Fn TIMEVAL_TO_TIMESPEC +and +.Fn TIMESPEC_TO_TIMEVAL +can be used to convert between +.Em struct timeval +and +.Em struct timespec . +.It +The following structure is used by +.Xr setitimer 2 , +among others: +.Bd -literal -offset indent +struct itimerval { + struct timeval it_interval; + struct timeval it_value; +}; +.Ed +.It +The following structure is used by +.Xr timer_settime 2 , +among others: +.Bd -literal -offset indent +struct itimerspec { + struct timespec it_interval; + struct timespec it_value; +}; +.Ed +.Pp +Both +.Em struct itimerval +and +.Em struct itimerspec +are used to specify when a timer expires. +Generally, +.Va it_interval +specifies the period between successive timer expirations. +A value zero implies that the alarm will fire only once. +If +.Va it_value +is non-zero, it indicates the time left to the next timer expiration. +A value zero implies that the timer is disabled. +.It +The following structure is used by +.Xr bintime 9 , +among others: +.Bd -literal -offset indent +struct bintime { + time_t sec; + uint64_t frac; +}; +.Ed +.Pp +The +.Va sec +member specifies the time in seconds and +.Va frac +represents a 64-bit fraction of seconds. +The +.Va struct bintime +is meant to be used in the kernel only. +It is further described in +.Xr timecounter 9 . +.El +.Sh EXAMPLES +It can be stressed that the traditional +.Tn UNIX +.Va timeval +and +.Va timespec +structures represent elapsed time, measured by the system clock +(see +.Xr hz 9 ) . +The following sketch implements a function suitable +for use in a context where the +.Va timespec +structure is required for a conditional timeout: +.Bd -literal -offset indent +static void +example(struct timespec *spec, time_t minutes) +{ + struct timeval elapsed; + + (void)gettimeofday(&elapsed, NULL); + + _DIAGASSERT(spec != NULL); + TIMEVAL_TO_TIMESPEC(&elapsed, spec); + + /* Add the offset for timeout in minutes. */ + spec->tv_sec = spec->tv_sec + minutes * 60; +} +.Ed +.Pp +A better alternative would use the more precise +.Xr clock_gettime 2 . +.Sh SEE ALSO +.Xr timeradd 3 , +.Xr tm 3 , +.Xr bintime_add 9 diff --git a/static/netbsd/man3/tm.3 b/static/netbsd/man3/tm.3 new file mode 100644 index 00000000..ad3afe79 --- /dev/null +++ b/static/netbsd/man3/tm.3 @@ -0,0 +1,112 @@ +.\" $NetBSD: tm.3,v 1.7 2024/10/13 01:30:45 riastradh Exp $ +.\" +.\" Copyright (c) 2011 Jukka Ruohonen <jruohonen@iki.fi> +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 14, 2011 +.Dt TM 3 +.Os +.Sh NAME +.Nm tm +.Nd time structure +.Sh SYNOPSIS +.In time.h +.Sh DESCRIPTION +The +.In time.h +header defines the +.Vt tm +structure that contains calendar dates and time broken down into components. +The following standards-compliant fields are present: +.Bl -column -offset indent \ +"Type" "Field " "Months since January 1 " "Range " +.It Sy Type Ta Sy Field Ta Sy Represents Ta Sy Range +.It Vt int Ta Va tm_sec Ta Seconds Ta [0, 60] +.It Vt int Ta Va tm_min Ta Minutes Ta [0, 59] +.It Vt int Ta Va tm_hour Ta Hours since midnight Ta [0, 23] +.It Vt int Ta Va tm_mday Ta Day of the month Ta [1, 31] +.It Vt int Ta Va tm_mon Ta Months since January Ta [0, 11] +.It Vt int Ta Va tm_year Ta Years since 1900 Ta +.It Vt int Ta Va tm_wday Ta Days since Sunday Ta [0, 6] +.It Vt int Ta Va tm_yday Ta Days since January 1 Ta [0, 365] +.It Vt int Ta Va tm_isdt Ta Positive if daylight savings Ta >= 0 +.El +.Pp +The +.Vt tm +structure is used by various common library routines such as +.Xr mktime 3 , +.Xr localtime 3 , +and +.Xr strptime 3 . +All fields described above are defined in the +.St -p1003.1-2008 +standard. +.Ss NetBSD Extensions +In addition, the following NetBSD-specific fields are available: +.Bl -column -offset indent \ +"Type " "Field " "Months since January 1" +.It Sy Type Ta Sy Field Ta Sy Represents +.It Vt long Ta Va tm_gmtoff Ta Offset from UTC in seconds +.It Vt "const char *" Ta Va tm_zone Ta Timezone abbreviation +.El +.Pp +The +.Va tm_zone +and +.Va tm_gmtoff +fields exist, and are filled in by applicable library routines, +only if arrangements to do so were made when the library containing +these functions was created. +There is no guarantee that these fields will continue to exist +in this form in future releases of +. Nx . +.Pp +The +.Fa tm_gmtoff +field denotes the offset (in seconds) of the time represented +from UTC, with positive values indicating east +of the Prime Meridian. +The +.Vt tm_zone +field will become invalid and point to freed storage if the corresponding +.Va "struct tm" +was returned by +.Xr localtime_rz 3 +and the +.Ft "const timezone_t" +.Fa tz +argument has been freed by +.Xr tzfree 3 . +.Sh SEE ALSO +.Xr asctime 3 , +.Xr offtime 3 , +.Xr timeval 3 , +.Xr wcsftime 3 +.Sh STANDARDS +The +.Vt tm +structure conforms to +.St -p1003.1-2008 +with respect to the described standard structure members. diff --git a/static/netbsd/man3/tree.3 b/static/netbsd/man3/tree.3 new file mode 100644 index 00000000..f4908111 --- /dev/null +++ b/static/netbsd/man3/tree.3 @@ -0,0 +1,610 @@ +.\" $NetBSD: tree.3,v 1.14 2019/05/24 21:32:05 wiz Exp $ +.\" $OpenBSD: tree.3,v 1.23 2011/07/09 08:43:01 jmc 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. +.\" * +.\" * 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 May 25, 2019 +.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_GENERATE , +.Nm RB_GENERATE_STATIC , +.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_SAFE , +.Nm RB_FOREACH_REVERSE , +.Nm RB_FOREACH_REVERSE_SAFE , +.Nm RB_INIT , +.Nm RB_INSERT , +.Nm RB_REMOVE +.Nd implementations of splay and red-black 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 "int" +.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" +.Pp +.Fn RB_PROTOTYPE "NAME" "TYPE" "FIELD" "CMP" +.Fn RB_PROTOTYPE_STATIC "NAME" "TYPE" "FIELD" "CMP" +.Fn RB_GENERATE "NAME" "TYPE" "FIELD" "CMP" +.Fn RB_GENERATE_STATIC "NAME" "TYPE" "FIELD" "CMP" +.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 "int" +.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_SAFE "VARNAME" "NAME" "RB_HEAD *head" "TEMP_VARNAME" +.Fn RB_FOREACH_REVERSE "VARNAME" "NAME" "RB_HEAD *head" +.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_REMOVE "NAME" "RB_HEAD *head" "struct TYPE *elm" +.Sh DESCRIPTION +.Bf -symbolic +This is a legacy interface; for new code, +.Xr rbtree 3 +is preferred. +.Ef +.Pp +These macros define data structures for different types of trees: +splay trees and red-black trees. +.Pp +In the macro definitions, +.Fa TYPE +is the name tag of a user defined structure that must contain a field named +.Fa FIELD , +of type +.Li SPLAY_ENTRY +or +.Li RB_ENTRY . +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 +.Li SPLAY_PROTOTYPE , +.Li RB_PROTOTYPE , +or +.Li RB_PROTOTYPE_STATIC . +The function bodies are generated with +.Li SPLAY_GENERATE , +.Li RB_GENERATE , +or +.Li 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 m operations +and n inserts on an initially empty tree as O((m + n)lg n). +The amortized cost for a sequence of m accesses to a splay tree is O(lg n). +.Pp +A splay tree is headed by a structure defined by the +.Fn SPLAY_HEAD +macro. +A +.Fa SPLAY_HEAD +structure is declared as follows: +.Bd -literal -offset indent +SPLAY_HEAD(HEADNAME, TYPE) 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 +.Fa "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 -literal -offset indent +SPLAY_HEAD(HEADNAME, TYPE) head = SPLAY_INITIALIZER(&head); +.Ed +.Pp +The +.Fn SPLAY_INSERT +macro inserts the new element +.Fa elm +into the tree. +Upon success, +.Dv NULL +is returned. +If a matching element already exists in the tree, the insertion is +aborted, and a pointer to the existing element is returned. +.Pp +The +.Fn SPLAY_REMOVE +macro removes the element +.Fa elm +from the tree pointed by +.Fa head . +Upon success, a pointer to the removed element is returned. +.Dv NULL +is returned if +.Fa elm +is not present in the tree. +.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 -literal -offset indent +SPLAY_FOREACH(np, NAME, &head) +.Ed +.Pp +The +.Fn SPLAY_EMPTY +macro should be used to check whether a splay tree is empty. +.Sh RED-BLACK TREES +A red-black tree is a binary search tree with the node color as an +extra attribute. +It fulfills a set of conditions: +.Pp +.Bl -enum -compact -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 O(lg n). +The maximum height of a red-black tree is 2lg (n+1). +.Pp +A red-black tree is headed by a structure defined by the +.Fn RB_HEAD +macro. +A +.Fa RB_HEAD +structure is declared as follows: +.Bd -literal -offset indent +RB_HEAD(HEADNAME, TYPE) 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 +macros, +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 . +.Pp +The function bodies are generated with the +.Fn RB_GENERATE +or +.Fn RB_GENERATE_STATIC +macros. +These macros take the same arguments as the +.Fn RB_PROTOTYPE +and +.Fn RB_PROTOTYPE_STATIC +macros, but should be used only once. +.Pp +Finally, +the +.Fa CMP +argument is the name of a function used to compare trees' nodes +with each other. +The function takes two arguments of type +.Fa "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 red-black tree can also be initialized statically by using the +.Fn RB_INITIALIZER +macro like this: +.Bd -literal -offset indent +RB_HEAD(HEADNAME, TYPE) head = RB_INITIALIZER(&head); +.Ed +.Pp +The +.Fn RB_INSERT +macro inserts the new element +.Fa elm +into the tree. +Upon success, +.Dv NULL +is returned. +If a matching element already exists in the tree, the insertion is +aborted, and a pointer to the existing element is returned. +.Pp +The +.Fn RB_REMOVE +macro removes the element +.Fa elm +from the tree pointed to by +.Fa head . +The element must be present in that tree. +.Fn RB_REMOVE +returns +.Fa elm . +.Pp +The +.Fn RB_FIND +macro can be used to find a particular element in the tree. +and +.Fn RB_NFIND +macros can be used to find a particular element in the tree. +.Fn RB_FIND +finds the node with the same key as +.Fa elm . +.Fn RB_NFIND +finds the first node greater than or equal to the search key. +.Bd -literal -offset indent +struct TYPE find, *res; +find.key = 30; +res = RB_FIND(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: +.Bd -literal -offset indent +for (np = RB_MIN(NAME, &head); np != NULL; np = RB_NEXT(NAME, &head, np)) +.Ed +.Pp +Or, for simplicity, one can use the +.Fn RB_FOREACH +or +.Fn RB_FOREACH_REVERSE +macros: +.Bd -literal -offset indent +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 +The +.Fn RB_EMPTY +macro should be used to check whether a red-black tree is empty. +.Sh EXAMPLES +The following example demonstrates how to declare a red-black tree +holding integers. +Values are inserted into it and the contents of the tree are printed +in order. +Lastly, the internal structure of the tree is printed. +.Bd -literal -offset 3n +#include <sys/tree.h> +#include <err.h> +#include <stdio.h> +#include <stdlib.h> + +struct node { + RB_ENTRY(node) entry; + int i; +}; + +int +intcmp(struct node *e1, struct node *e2) +{ + return (e1->i < e2->i ? -1 : e1->i > e2->i); +} + +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() +{ + 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("\en"); + return (0); +} +.Ed +.Sh NOTES +Some of these macros or functions perform no error checking, +and invalid usage leads to undefined behaviour. +In the case of macros or functions that expect their arguments +to be elements that are present in the tree, passing an element +that is not present in the tree is invalid. +.Pp +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 free'd, 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 rbtree 3 +.Sh AUTHORS +The author of the tree macros is +.An Niels Provos . diff --git a/static/netbsd/man3/typeof.3 b/static/netbsd/man3/typeof.3 new file mode 100644 index 00000000..d23030bc --- /dev/null +++ b/static/netbsd/man3/typeof.3 @@ -0,0 +1,63 @@ +.\" $NetBSD: typeof.3,v 1.2 2010/12/19 08:10:09 jruoho Exp $ +.\" +.\" Copyright (c) 2010 Jukka Ruohonen <jruohonen@iki.fi> +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 19, 2010 +.Dt TYPEOF 3 +.Os +.Sh NAME +.Nm typeof +.Nd GNU extension for type of an expression +.Sh SYNOPSIS +.Ft type +.Fn typeof "expression" +.Sh DESCRIPTION +The +.Fn typeof +construct can be used to obtain the type of an expression. +The syntax is comparable to that of +.Fn sizeof , +but semantically +.Fn typeof +operates like a type name defined with +.Em typedef . +.Sh EXAMPLES +The following is a typical example of a type-generic macro: +.Bd -literal -offset indent +#define MAX(a, b) ({ \\ + typeof(a) _a = (a); \\ + typeof(b) _b = (b); \\ + _a > _b ? _a : _b; \\ +}) +.Ed +.Sh SEE ALSO +.Xr gcc 1 , +.Xr __alignof__ 3 , +.Xr attribute 3 , +.Xr offsetof 3 +.Sh CAVEATS +The +.Fn typeof +construct is a non-standard, compiler-specific extension. diff --git a/static/netbsd/man3/types.3 b/static/netbsd/man3/types.3 new file mode 100644 index 00000000..df205b69 --- /dev/null +++ b/static/netbsd/man3/types.3 @@ -0,0 +1,223 @@ +.\" $NetBSD: types.3,v 1.7 2020/06/08 17:28:10 sevan Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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) 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. +.\" +.\" @(#)types.5 8.1 (Berkeley) 6/5/93 +.\" +.Dd April 10, 2011 +.Dt TYPES 3 +.Os +.Sh NAME +.Nm types +.Nd standard system data types +.Sh SYNOPSIS +.In sys/types.h +.Sh DESCRIPTION +The +.In sys/types.h +header contains the common data types used in the system. +Although these are meant to be used within the kernel, +most of the system data types are accessible also to user code. +A companion header +.In sys/param.h , +typically used in the kernel, +includes +.In sys/types.h +and provides additional types as well as other facilities (see +.Xr param 3 ) . +.Ss Standard Types +The following standards-compliant system data types are defined: +.Bl -column -offset indent \ +"suseconds_t " "process and process group IDs " "clock_settime(3) " +.It Sy Type Ta Sy Typical use Ta Sy Example +.It Va blkcnt_t Ta file block counts Ta Xr stat 2 +.It Va blksize_t Ta block sizes Ta Xr stat 2 +.It Va clock_t Ta system clock ticks Ta Xr clock 3 +.It Va clockid_t Ta clock IDs Ta Xr clock_settime 2 +.It Va dev_t Ta device IDs Ta Xr devname 3 +.It Va fsblkcnt_t Ta file system block counts Ta - +.It Va fsfilcnt_t Ta file system file counts Ta - +.It Va gid_t Ta group IDs Ta Xr getgid 2 +.It Va id_t Ta general identifier Ta Xr pset 3 +.It Va ino_t Ta file serial numbers Ta Xr fs 5 +.It Va key_t Ta interprocess communication Ta Xr ftok 3 +.It Va mode_t Ta file attributes Ta Xr stat 2 +.It Va nlink_t Ta link counts Ta Xr stat 2 +.It Va off_t Ta file sizes Ta Xr fseek 3 +.It Va pid_t Ta process and process group IDs Ta Xr getpid 2 +.It Va size_t Ta size of objects Ta Xr stddef 3 +.It Va ssize_t Ta count of bytes Ta Xr write 2 +.It Va suseconds_t Ta microseconds Ta Xr gettimeofday 2 +.It Va time_t Ta time in seconds Ta Xr time 3 +.It Va timer_t Ta timer IDs Ta Xr timer_create 2 +.\" +.\" XXX: Following are undefined in NetBSD at the time of writing: +.\" +.\".It Va trace_attr_t Ta trace stream attributes Ta - +.\".It Va trace_event_id_t Ta trace event type Ta - +.\".It Va trace_event_set_t Ta trace event type set Ta - +.\".It Va trace_id_t Ta trace stream ID Ta - +.It Va uid_t Ta user IDs Ta Xr setuid 2 +.It Va useconds_t Ta time in microseconds Ta Xr usleep 3 +.El +.Pp +In addition, when included in user applications, +.In sys/types.h +includes +.In pthread.h , +and thus it defines also the types used in the +.Tn POSIX +Threads Library, +.Xr pthread 3 . +.Pp +Each described type may vary across machines and operating systems. +Only the following properties are guaranteed by the +.St -p1003.1-2001 +standard: +.Bl -enum -offset indent +.It +The type +.Em ssize_t +is capable of storing integer values at least in the range [\-1, +.Dv SSIZE_MAX ] . +.It +The type +.Em useconds_t +is an unsigned integer capable of storing +values at least in the range [0, 1000000]. +.It +The type +.Em suseconds_t +is a signed integer capable of storing +values at least in the range [\-1, 1000000]. +.It +The +.Em time_t +and +.Em clock_t +types are either integers or real-floating types. +.It +The following types are integers: +.Em gid_t , +.Em id_t , +.Em mode_t , +.Em nlink_t , +and +.Em uid_t . +.It +The following types are signed integers: +.Em blkcnt_t , +.Em blksize_t , +.Em off_t , +.Em pid_t , +and +.Em ssize_t . +.It +The following types are unsigned integers: +.Em fsblkcnt_t , +.Em fsfilcnt_t , +.Em ino_t , +and +.Em size_t . +.El +.Ss NetBSD-specific Types +In addition to the standard types, +.In sys/types.h +defines some data types specific to +.Nx . +These are mostly used in the kernel. +A portable implementation should not rely +on these types to be available in other systems. +Examples include: +.Bl -column -offset indent \ +"suseconds_t " "synonym for uint64_t " "getdevmajor(3) " +.It Sy Type Ta Sy Typical use Ta Sy Example +.It Va cpuid_t Ta CPU IDs Ta Xr cpuset 3 +.It Va daddr_t Ta disk address Ta Xr buffercache 9 +.It Va devmajor_t Ta major device number Ta Xr getdevmajor 3 +.It Va lwp_t Ta typedef of Va struct lwp Ta Xr kthread 9 +.It Va u_quad_t Ta synonym for Va uint64_t Ta Xr strtouq 3 +.El +.Pp +It can be noted that the standard +.Dq C99 types +described in +.Xr stdint 3 +are preferred to the older fixed size integer types prefixed with an +.Dq u_ +(in other words, +.Va uint32_t +should be used instead of +.Va u_int32_t ) . +.Sh SEE ALSO +.Xr param 3 , +.Xr stdbool 3 , +.Xr stddef 3 , +.Xr stdint 3 , +.Xr stdlib 3 , +.Xr unistd 3 +.Sh STANDARDS +The +.In sys/types.h +header conforms to +.St -p1003.1-2001 +with respect to the described standard types. +.Sh HISTORY +The +.In sys/types.h +header first appeared in +.At v7 . +In the current form the header appeared in +.Nx 0.9 . diff --git a/static/netbsd/man3/uchar.3 b/static/netbsd/man3/uchar.3 new file mode 100644 index 00000000..1a2a70ad --- /dev/null +++ b/static/netbsd/man3/uchar.3 @@ -0,0 +1,151 @@ +.\" $NetBSD: uchar.3,v 1.2 2024/08/15 21:19:45 riastradh Exp $ +.\" +.\" Copyright (c) 2024 The NetBSD Foundation, 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. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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 15, 2024 +.Dt UCHAR 3 +.Os +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh NAME +.Nm uchar +.Nd Unicode utilities +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SYNOPSIS +.In uchar.h +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh DESCRIPTION +The +.In uchar.h +header file declares types and functions for manipulating Unicode code +units. +.\"""""""""""""""""""""""""""""""""""""" +.Ss Types +.Bl -tag -width ".Vt char32_t" +.It Vt char8_t +(C23) +Unsigned integer type for UTF-8 code units. +.Pp +Same type as +.Vt unsigned char . +.It Vt char16_t +Unsigned integer type for UTF-16 code units. +.Pp +Same type as +.Vt uint_least16_t +from +.In stdint.h . +May represent both surrogate code points, i.e., code points in the +interval [0xd800,0xdfff], and Unicode scalar values in the Basic +Multilingual Plane, which are the 16-bit code points other than +surrogate code points. +.It Vt char32_t +Unsigned integer type for UTF-32 code units. +.Pp +Same type as +.Vt uint_least32_t +from +.In stdint.h . +Can represent all Unicode scalar values, not just those in the Basic +Multilingual Plane. +Intended to represent only Unicode scalar values, not surrogate code +points. +.It Vt mbstate_t +Opaque multibyte conversion state. +.Pp +Same type as in +.Vt stddef.h +and +.Vt wchar.h . +.It Vt size_t +Unsigned integer type to represent array sizes. +.Pp +Same type as in +.Vt stddef.h , +.Vt stdint.h , +and +.Vt sys/types.h . +.El +.\"""""""""""""""""""""""""""""""""""""" +.Ss Functions +The +.In uchar.h +header file declares the functions +.Xr mbrtoc8 3 , +.Xr c8rtomb 3 , +.Xr mbrtoc16 3 , +.Xr c16rtomb 3 , +.Xr mbrtoc32 3 , +and +.Xr c32rtomb 3 +for conversion between multibyte sequences and UTF-8/UTF-16/UTF-32 code +units. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh SEE ALSO +.Xr c8rtomb 3 , +.Xr c16rtomb 3 , +.Xr c32rtomb 3 , +.Xr mbrtoc8 3 , +.Xr mbrtoc16 3 , +.Xr mbrtoc32 3 +.Rs +.%B The Unicode Standard +.%O Version 15.0 \(em Core Specification +.%Q The Unicode Consortium +.%D September 2022 +.%U https://www.unicode.org/versions/Unicode15.0.0/UnicodeStandard-15.0.pdf +.Re +.Rs +.%A P. Hoffman +.%A F. Yergeau +.%T UTF-16, an encoding of ISO 10646 +.%R RFC 2781 +.%D February 2000 +.%I Internet Engineering Task Force +.%U https://datatracker.ietf.org/doc/html/rfc2781 +.Re +.Rs +.%A F. Yergeau +.%T UTF-8, a transformation format of ISO 10646 +.%R RFC 3629 +.%D November 2003 +.%I Internet Engineering Task Force +.%U https://datatracker.ietf.org/doc/html/rfc3629 +.Re +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh STANDARDS +The +.In uchar.h +header file conforms to +.St -isoC-2011 +.\" .St -isoC-2023 +.\" .\" XXX PR misc/58600: man pages lack C17, C23, C++98, C++03, C++11, C++17, C++20, C++23 citation syntax +and +.St -p1003.1-2024 . +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.Sh HISTORY +The +.In uchar.h +header file first appeared in +.Nx 11.0 . diff --git a/static/netbsd/man3/unistd.3 b/static/netbsd/man3/unistd.3 new file mode 100644 index 00000000..e632027a --- /dev/null +++ b/static/netbsd/man3/unistd.3 @@ -0,0 +1,109 @@ +.\" $NetBSD: unistd.3,v 1.4 2011/08/09 18:11:38 jruoho Exp $ +.\" +.\" Copyright (c) 2011 Jukka Ruohonen <jruohonen@iki.fi> +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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 9, 2011 +.Dt UNISTD 3 +.Os +.Sh NAME +.Nm unistd +.Nd standard symbolic constants and types +.Sh SYNOPSIS +.In unistd.h +.Sh DESCRIPTION +The +.In unistd.h +header forms the basis of the Portable Operating System Interface for Unix +.Pq Tn POSIX +.Tn API . +It includes definitions for numerous functions, symbolic constants, and types. +Among these are: +.Bl -bullet -offset indent +.It +The implementation-defined +.Dv NULL +pointer constant. +.It +Types such as +.Vt size_t , +.Vt ssize_t , +.Vt pid_t , +and +.Vt intptr_t . +.It +Various limits and other symbolic constants described in +.Xr pathconf 2 +and +.Xr sysconf 3 . +.It +Prototypes for several important system calls and library routines such as +.Xr chown 2 , +.Xr dup 2 , +.Xr execl 3 , +.Xr fork 2 , +.Xr pipe 2 , +.Xr rmdir 2 , +.Xr setuid 2 , +and +.Xr write 2 . +.It +The symbolic constant +.Dv _POSIX_VERSION +that defines the version of the +.Tn POSIX +standard to which the implementation conforms. +.It +Various other +.Dv _POSIX +-prefixed symbolic constants that indicate whether +the system implements some optional part of the standard. +Examples include such constants as +.Dv _POSIX_IPV6 +for +.Xr inet6 4 +functionality and +.Dv _POSIX_ASYNCHRONOUS_IO +for +.Xr aio 3 . +.El +.Sh SEE ALSO +.Xr limits 3 , +.Xr stddef 3 , +.Xr stdint 3 , +.Xr stdlib 3 , +.Xr types 3 +.Sh STANDARDS +The +.In unistd.h +header conforms to +.St -p1003.1-2001 . +.\" +.\" XXX: fill this. +.\" +.\".Sh HISTORY +.\" A +.\" .In unistd.h +.\" header first appeared in +.\" ??? |