diff options
Diffstat (limited to 'share/man/man3')
| -rw-r--r-- | share/man/man3/Makefile | 26 | ||||
| -rw-r--r-- | share/man/man3/assert.3 | 86 | ||||
| -rw-r--r-- | share/man/man3/bitstring.3 | 179 | ||||
| -rw-r--r-- | share/man/man3/end.3 | 67 | ||||
| -rw-r--r-- | share/man/man3/intro.3 | 162 | ||||
| -rw-r--r-- | share/man/man3/queue.3 | 454 | ||||
| -rw-r--r-- | share/man/man3/stdarg.3 | 205 |
7 files changed, 1179 insertions, 0 deletions
diff --git a/share/man/man3/Makefile b/share/man/man3/Makefile new file mode 100644 index 0000000..673ff36 --- /dev/null +++ b/share/man/man3/Makefile @@ -0,0 +1,26 @@ +# @(#)Makefile 8.2 (Berkeley) 12/13/93 + +MAN3= assert.0 bitstring.0 end.0 intro.0 queue.0 stdarg.0 +MLINKS+=end.3 edata.3 end.3 etext.3 moncontrol.3 monstartup.3 +MLINKS+=queue.3 list_entry.3 queue.3 list_head.3 queue.3 list_init.3 +MLINKS+=queue.3 list_insert_after.3 queue.3 list_insert_head.3 +MLINKS+=queue.3 list_remove.3 queue.3 tailq_entry.3 queue.3 tailq_head.3 +MLINKS+=queue.3 tailq_init.3 queue.3 tailq_insert_after.3 +MLINKS+=queue.3 tailq_insert_head.3 queue.3 tailq_insert_tail.3 +MLINKS+=queue.3 tailq_remove.3 queue.3 circleq_entry.3 queue.3 circleq_head.3 +MLINKS+=queue.3 circleq_init.3 queue.3 circleq_insert_after.3 +MLINKS+=queue.3 circleq_insert_before.3 queue.3 circleq_insert_head.3 +MLINKS+=queue.3 circleq_insert_tail.3 queue.3 circleq_remove.3 +MLINKS+=stdarg.3 varargs.3 stdarg.3 va_arg.3 stdarg.3 va_end.3 +MLINKS+=stdarg.3 va_start.3 + +all: ${MAN3} + +clean depend lint tags: + +cleandir: + rm -f ${MAN3} + +install: maninstall + +.include <bsd.prog.mk> diff --git a/share/man/man3/assert.3 b/share/man/man3/assert.3 new file mode 100644 index 0000000..2a9c8f9 --- /dev/null +++ b/share/man/man3/assert.3 @@ -0,0 +1,86 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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 9, 1993 +.Dt ASSERT 3 +.Os +.Sh NAME +.Nm assert +.Nd expression verification macro +.Sh SYNOPSIS +.Fd #include <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 is written to the +.Em stderr +and the function +.Xr _exit 2 +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 +.Fl NDEBUG +option, see +.Xr cc 1 . +.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\n", \e + "expression", __FILE__, __LINE__); +.Ed +.Sh HISTORY +A +.Nm assert +macro appeared in +.At v6 . diff --git a/share/man/man3/bitstring.3 b/share/man/man3/bitstring.3 new file mode 100644 index 0000000..11497d9 --- /dev/null +++ b/share/man/man3/bitstring.3 @@ -0,0 +1,179 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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 July 19, 1993 +.Dt BITSTRING 3 +.Os BSD 4 +.Sh NAME +.Nm bit_alloc , +.Nm bit_clear , +.Nm bit_decl , +.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 +.Fd #include <bitstring.h> +.Ft bitstr_t * +.Fn bit_alloc "int nbits" +.Fn bit_decl "bit_str name" "int nbits" +.Fn bit_clear "bit_str name" "int bit" +.Fn bit_ffc "bit_str name" "int nbits" "int *value" +.Fn bit_ffs "bit_str name" "int nbits" "int *value" +.Fn bit_nclear "bit_str name" "int start" "int stop" +.Fn bit_nset "bit_str name" "int start" "int stop" +.Fn bit_set "bit_str name" "int bit" +.Fn bitstr_size "int nbits" +.Fn bit_test "bit_str name" "int 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 EXAMPLE +.Bd -literal -offset indent +#include <limits.h> +#include <bitstring.h> + +... +#define LPR_BUSY_BIT 0 +#define LPR_FORMAT_BIT 1 +#define LPR_DOWNLOAD_BIT 2 +... +#define LPR_AVAILABLE_BIT 9 +#define LPR_MAX_BITS 10 + +make_lpr_available() +{ + bitstr_t bit_decl(bitlist, LPR_MAX_BITS); + ... + bit_nclear(bitlist, 0, LPR_MAX_BITS - 1); + ... + if (!bit_test(bitlist, LPR_BUSY_BIT)) { + bit_clear(bitlist, LPR_FORMAT_BIT); + bit_clear(bitlist, LPR_DOWNLOAD_BIT); + bit_set(bitlist, LPR_AVAILABLE_BIT); + } +} +.Ed +.Sh SEE ALSO +.Xr malloc 3 +.Sh HISTORY +The +.Nm bitstring +functions first appeared in 4.4BSD. diff --git a/share/man/man3/end.3 b/share/man/man3/end.3 new file mode 100644 index 0000000..3f1afa6 --- /dev/null +++ b/share/man/man3/end.3 @@ -0,0 +1,67 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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 January 24, 1994 +.Dt END 3 +.Os +.Sh NAME +.Nm end , +.Nm etext , +.Nm edata +.Nd end boundaries of image segments +.Sh SYNOPSIS +.Vt extern end; +.Vt extern etext; +.Vt extern edata; +.Sh DESCRIPTION +The global variables +.Va end , extext +and +.Va edata +correspond to the +the next address following the end +of the text segment, +the initialized data segment and the +end of the data segment +.Pq Tn BSS . +These values are initially set at execution time +by +.Xr brk 2 . +.Sh SEE ALSO +.Xr brk 2 , +.Xr malloc 3 +.Sh HISTORY +A +.Nm end +manual appeared in +.At v6 . diff --git a/share/man/man3/intro.3 b/share/man/man3/intro.3 new file mode 100644 index 0000000..ea77402 --- /dev/null +++ b/share/man/man3/intro.3 @@ -0,0 +1,162 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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 June 5, 1993 +.Dt INTRO 3 +.Os BSD 4 +.Sh NAME +.Nm intro +.Nd introduction to the C libraries +.Sh DESCRIPTION +This section provides an overview of the C +library functions, their error returns and other +common definitions and concepts. +Most of these functions are available from the C library, +.Em libc +(see +.Xr libc 3 ) . +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 libraries (followed by the loader flag): +.Bl -tag -width "libc (-lc)" +.It Xr libc Pq Fl l Ns Ar c +Standard C library functions. (See +.Xr libc 3 . ) When using the C compiler +.Xr cc 1 , +it is not necessary +to supply the loader flag +.Fl l Ns Ar c +for these functions. +There are several `libraries' or groups of functions included inside of +.Xr libc : the standard +.Tn I/O +routines, +database routines, +bit operators, +string operators, +character tests and character operators, +des encryption routines, +storage allocation, time functions, signal handling and more. +.It Xo +.Xr libcurses +.Pf ( Fl l Ns Ar curses +.Fl l Ns Ar termcap ) +.Xc +Terminal independent screen management routines +for two dimensional non-bitmap display terminals. +(See +.Xr curses 3 . ) +.It Xr 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 Xr libkvm +.It Xr libl Pq Fl l Ns Ar l +The library for +.Xr lex 1 . +.\" .It Xr libln +.It Xr libm Pq Fl l Ns Ar m +The math library, +.Em libm . +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 Xr libmp Pq Fl l Ns Ar mp +.\" .It Xr libom +.\" Old math library. +.It Xr libplot Pq Fl l Ns Ar plot +Device independent plotting functions. +(See +.Xr plot 3 . ) +.It Xr libplotf77 Pq Fl l Ns Ar plotf77 +The device independent plotting functions for fortran. +(See +.Xr plot 3 . ) +.\" .It Xr libresolv Pq Fl l Ns Ar resolv +.\" Routines for network address resolution. +.It Xr libtermcap Fl l Ns Ar termcap +The terminal independent operation library package. (See +.Xr termcap 3 . ) +.\" .It libvt0.a +.It Xr liby Pq Fl l Ns Ar y +The library for +.Xr yacc 1 . +.El +.Sh FILES +.Bl -tag -width /usr/lib/libm_p.a -compact +.It Pa /usr/lib/libc.a +the C library +.It Pa /usr/lib/libm.a +the math library +.It Pa /usr/lib/libc_p.a +the C library compiled for profiling +.It Pa /usr/lib/libm_p.a +the math library compiled for profiling +.El +.Sh SEE ALSO +.\" .Xr libc 3 , +.Xr stdio 3 , +.Xr math 3 , +.Xr intro 2 , +.Xr cc 1 , +.Xr ld 1 , +.Xr nm 1 +.\" .Sh LIST OF FUNCTIONS +.\" .Bl -column "strncasecmpxxx" "system" +.\" .Sy Name Description +.\" .El +.Sh HISTORY +An +.Nm intro +manual appeared in +.At v7 . diff --git a/share/man/man3/queue.3 b/share/man/man3/queue.3 new file mode 100644 index 0000000..d31a58f --- /dev/null +++ b/share/man/man3/queue.3 @@ -0,0 +1,454 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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.2 (Berkeley) 1/24/94 +.\" +.Dd "January 24, 1994" +.Dt QUEUE 3 +.Os BSD 4 +.Sh NAME +.Nm LIST_ENTRY , +.Nm LIST_HEAD , +.Nm LIST_INIT , +.Nm LIST_INSERT_AFTER , +.Nm LIST_INSERT_HEAD , +.Nm LIST_REMOVE , +.Nm TAILQ_ENTRY , +.Nm TAILQ_HEAD , +.Nm TAILQ_INIT , +.Nm TAILQ_INSERT_AFTER , +.Nm TAILQ_INSERT_HEAD , +.Nm TAILQ_INSERT_TAIL , +.Nm TAILQ_REMOVE , +.Nm CIRCLEQ_ENTRY , +.Nm CIRCLEQ_HEAD , +.Nm CIRCLEQ_INIT , +.Nm CIRCLEQ_INSERT_AFTER , +.Nm CIRCLEQ_INSERT_BEFORE , +.Nm CIRCLEQ_INSERT_HEAD , +.Nm CIRCLEQ_INSERT_TAIL , +.Nm CIRCLEQ_REMOVE +.Nd implementations of lists, tail queues, and circular queues +.Sh SYNOPSIS +.Fd #include <sys/queue.h> +.sp +.Fn LIST_ENTRY "TYPE" +.Fn LIST_HEAD "HEADNAME" "TYPE" +.Fn LIST_INIT "LIST_HEAD *head" +.Fn LIST_INSERT_AFTER "LIST_ENTRY *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" +.sp +.Fn TAILQ_ENTRY "TYPE" +.Fn TAILQ_HEAD "HEADNAME" "TYPE" +.Fn TAILQ_INIT "TAILQ_HEAD *head" +.Fn TAILQ_INSERT_AFTER "TAILQ_HEAD *head" "TYPE *listelm" "TYPE *elm" "TAILQ_ENTRY NAME" +.Fn TAILQ_INSERT_HEAD "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME" +.Fn TAILQ_INSERT_TAIL "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME" +.Fn TAILQ_REMOVE "TAILQ_HEAD *head" "TYPE *elm" "TAILQ_ENTRY NAME" +.sp +.Fn CIRCLEQ_ENTRY "TYPE" +.Fn CIRCLEQ_HEAD "HEADNAME" "TYPE" +.Fn CIRCLEQ_INIT "CIRCLEQ_HEAD *head" +.Fn CIRCLEQ_INSERT_AFTER "CIRCLEQ_HEAD *head" "TYPE *listelm" "TYPE *elm" "CIRCLEQ_ENTRY NAME" +.Fn CIRCLEQ_INSERT_BEFORE "CIRCLEQ_HEAD *head" "TYPE *listelm" "TYPE *elm" "CIRCLEQ_ENTRY NAME" +.Fn CIRCLEQ_INSERT_HEAD "CIRCLEQ_HEAD *head" "TYPE *elm" "CIRCLEQ_ENTRY NAME" +.Fn CIRCLEQ_INSERT_TAIL "CIRCLEQ_HEAD *head" "TYPE *elm" "CIRCLEQ_ENTRY NAME" +.Fn CIRCLEQ_REMOVE "CIRCLEQ_HEAD *head" "TYPE *elm" "CIRCLEQ_ENTRY NAME" +.Sh DESCRIPTION +These macros define and operate on three types of data structures: +lists, tail queues, and circular queues. +All three 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 +Lists are the simplest of the three data structures and support +only the above functionality. +.Pp +Tail queues add the following functionality: +.Bl -enum -compact -offset indent +.It +Entries can be added at the end of a list. +.El +However: +.Bl -enum -compact -offset indent +.It +All list insertions and removals must specify the head of the list. +.It +Each head entry requires two pointers rather than one. +.It +Code size is about 15% greater and operations run about 20% slower +than 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 +Entries can be added before another entry. +.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 LIST_ENTRY , +.Li TAILQ_ENTRY , +or +.Li CIRCLEQ_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 TAILQ_HEAD , +or +.Li CIRCLEQ_HEAD . +See the examples below for further explanation of how these +macros are used. +.Sh LISTS +A list is headed by a structure defined by the +.Nm LIST_HEAD +macro. +This structure contains a single pointer to the first element +on the list. +The elements are doubly linked so that an arbitrary element can be +removed without traversing the list. +New elements can be added to the list after an existing element 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 +.sp +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 +.sp +(The names +.Li head +and +.Li headp +are user selectable.) +.Pp +The macro +.Nm LIST_ENTRY +declares a structure that connects the elements in +the list. +.Pp +The macro +.Nm LIST_INIT +initializes the list referenced by +.Fa head . +.Pp +The macro +.Nm LIST_INSERT_HEAD +inserts the new element +.Fa elm +at the head of the list. +.Pp +The macro +.Nm LIST_INSERT_AFTER +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +The macro +.Nm LIST_REMOVE +removes the element +.Fa elm +from the list. +.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); + /* Forward traversal. */ +for (np = head.lh_first; np != NULL; np = np->entries.le_next) + np-> ... + +while (head.lh_first != NULL) /* Delete. */ + LIST_REMOVE(head.lh_first, entries); +.Ed +.Sh TAIL QUEUES +A tail queue is headed by a structure defined by the +.Nm TAILQ_HEAD +macro. +This structure contains a pair of pointers, +one to the first element in the tail queue and the other to +the last element in the tail queue. +The elements are doubly linked so that an arbitrary element can be +removed without traversing the tail queue. +New elements can be added to the tail queue after an existing element, +at the head of the tail queue, or at the end of the tail queue. +A +.Fa TAILQ_HEAD +structure is declared as follows: +.Bd -literal -offset indent +TAILQ_HEAD(HEADNAME, TYPE) head; +.Ed +.sp +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 +.sp +(The names +.Li head +and +.Li headp +are user selectable.) +.Pp +The macro +.Nm TAILQ_ENTRY +declares a structure that connects the elements in +the tail queue. +.Pp +The macro +.Nm TAILQ_INIT +initializes the tail queue referenced by +.Fa head . +.Pp +The macro +.Nm TAILQ_INSERT_HEAD +inserts the new element +.Fa elm +at the head of the tail queue. +.Pp +The macro +.Nm TAILQ_INSERT_TAIL +inserts the new element +.Fa elm +at the end of the tail queue. +.Pp +The macro +.Nm TAILQ_INSERT_AFTER +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +The macro +.Nm TAILQ_REMOVE +removes the element +.Fa elm +from the tail queue. +.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); + /* Forward traversal. */ +for (np = head.tqh_first; np != NULL; np = np->entries.tqe_next) + np-> ... + /* Delete. */ +while (head.tqh_first != NULL) + TAILQ_REMOVE(&head, head.tqh_first, entries); +.Ed +.Sh CIRCULAR QUEUES +A circular queue is headed by a structure defined by the +.Nm CIRCLEQ_HEAD +macro. +This structure contains a pair of pointers, +one to the first element in the circular queue and the other to the +last element in the circular queue. +The elements are doubly linked so that an arbitrary element can be +removed without traversing the 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 +of the queue. +A +.Fa CIRCLEQ_HEAD +structure is declared as follows: +.Bd -literal -offset indent +CIRCLEQ_HEAD(HEADNAME, TYPE) head; +.Ed +.sp +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 circular queue. +A pointer to the head of the circular queue can later be declared as: +.Bd -literal -offset indent +struct HEADNAME *headp; +.Ed +.sp +(The names +.Li head +and +.Li headp +are user selectable.) +.Pp +The macro +.Nm CIRCLEQ_ENTRY +declares a structure that connects the elements in +the circular queue. +.Pp +The macro +.Nm CIRCLEQ_INIT +initializes the circular queue referenced by +.Fa head . +.Pp +The macro +.Nm CIRCLEQ_INSERT_HEAD +inserts the new element +.Fa elm +at the head of the circular queue. +.Pp +The macro +.Nm CIRCLEQ_INSERT_TAIL +inserts the new element +.Fa elm +at the end of the circular queue. +.Pp +The macro +.Nm CIRCLEQ_INSERT_AFTER +inserts the new element +.Fa elm +after the element +.Fa listelm . +.Pp +The macro +.Nm CIRCLEQ_INSERT_BEFORE +inserts the new element +.Fa elm +before the element +.Fa listelm . +.Pp +The macro +.Nm CIRCLEQ_REMOVE +removes the element +.Fa elm +from the circular queue. +.Sh CIRCULAR QUEUE EXAMPLE +.Bd -literal +CIRCLEQ_HEAD(circleq, entry) head; +struct circleq *headp; /* Circular queue head. */ +struct entry { + ... + CIRCLEQ_ENTRY entries; /* Circular queue. */ + ... +} *n1, *n2, *np; + +CIRCLEQ_INIT(&head); /* Initialize the circular queue. */ + +n1 = malloc(sizeof(struct entry)); /* Insert at the head. */ +CIRCLEQ_INSERT_HEAD(&head, n1, entries); + +n1 = malloc(sizeof(struct entry)); /* Insert at the tail. */ +CIRCLEQ_INSERT_TAIL(&head, n1, entries); + +n2 = malloc(sizeof(struct entry)); /* Insert after. */ +CIRCLEQ_INSERT_AFTER(&head, n1, n2, entries); + +n2 = malloc(sizeof(struct entry)); /* Insert before. */ +CIRCLEQ_INSERT_BEFORE(&head, n1, n2, entries); + /* Forward traversal. */ +for (np = head.cqh_first; np != (void *)&head; np = np->entries.cqe_next) + np-> ... + /* Reverse traversal. */ +for (np = head.cqh_last; np != (void *)&head; np = np->entries.cqe_prev) + np-> ... + /* Delete. */ +while (head.cqh_first != (void *)&head) + CIRCLEQ_REMOVE(&head, head.cqh_first, entries); +.Ed +.Sh HISTORY +The +.Nm queue +functions first appeared in 4.4BSD. diff --git a/share/man/man3/stdarg.3 b/share/man/man3/stdarg.3 new file mode 100644 index 0000000..3b9a820 --- /dev/null +++ b/share/man/man3/stdarg.3 @@ -0,0 +1,205 @@ +.\" 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. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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 5, 1993 +.Dt STDARG 3 +.Os +.Sh NAME +.Nm stdarg +.Nd variable argument lists +.Sh SYNOPSIS +.Fd #include <stdarg.h> +.Ft void +.Fn va_start "va_list ap" last +.Ft type +.Fn va_arg "va_list ap" type +.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 +.Aq Pa 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 , +and +.Fn va_end . +.Pp +The +.Fn va_start +macro initializes +.Fa ap +for subsequent use by +.Fn va_arg +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 +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_end +macro handles a normal return from the function whose variable argument +list was initialized by +.Fn va_start . +.Pp +The +.Fn va_end +macro returns no value. +.Sh EXAMPLES +The function +.Em foo +takes a string of format characters and prints out the argument +associated with each format character based on the type. +.Bd -literal -offset indent +void foo(char *fmt, ...) +{ + va_list ap; + int d; + char c, *p, *s; + + va_start(ap, fmt); + while (*fmt) + switch(*fmt++) { + case 's': /* string */ + s = va_arg(ap, char *); + printf("string %s\en", s); + break; + case 'd': /* int */ + d = va_arg(ap, int); + printf("int %d\en", d); + break; + case 'c': /* char */ + c = va_arg(ap, char); + printf("char %c\en", c); + break; + } + va_end(ap); +} +.Ed +.Sh STANDARDS +The +.Fn va_start , +.Fn va_arg , +and +.Fn va_end +macros conform to +.St -ansiC . +.Sh COMPATIBILITY +These macros are +.Em not +compatible with the historic macros they replace. +A backward compatible version can be found in the include +file +.Aq Pa varargs.h . +.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 . |
