[src/trunk]: src/share/man/man3 Add a separate varargs(3) manual page, reusin...

[kleink <kleink%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/0773d67febd2
branches:  trunk
changeset: 521757:0773d67febd2
user:      kleink <kleink%NetBSD.org@localhost>
date:      Mon Feb 04 20:09:46 2002 +0000

description:
Add a separate varargs(3) manual page, reusing stdarg(3) contents, and
remove the name `varargs' from stdarg(3); inspired by conversation with
Charles Hannum.

diffstat:

 share/man/man3/Makefile  |    6 +-
 share/man/man3/stdarg.3  |    3 +-
 share/man/man3/varargs.3 |  206 +++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 210 insertions(+), 5 deletions(-)

diffs (250 lines):

diff -r 12a718b48f7b -r 0773d67febd2 share/man/man3/Makefile
--- a/share/man/man3/Makefile   Mon Feb 04 19:07:47 2002 +0000
+++ b/share/man/man3/Makefile   Mon Feb 04 20:09:46 2002 +0000
@@ -1,8 +1,8 @@
-#      $NetBSD: Makefile,v 1.22 2001/10/22 04:37:57 lukem Exp $
+#      $NetBSD: Makefile,v 1.23 2002/02/04 20:09:46 kleink Exp $
 #      @(#)Makefile    8.2 (Berkeley) 12/13/93
 
 MAN=   _DIAGASSERT.3 assert.3 bitstring.3 dlfcn.3 end.3 intro.3 queue.3 \
-       stdarg.3
+       stdarg.3 varargs.3
 MLINKS+=end.3 edata.3 end.3 etext.3
 MLINKS+=queue.3 LIST_EMPTY.3
 MLINKS+=queue.3 LIST_ENTRY.3 queue.3 LIST_FIRST.3 queue.3 LIST_HEAD.3
@@ -28,7 +28,7 @@
 MLINKS+=queue.3 CIRCLEQ_INSERT_HEAD.3 queue.3 CIRCLEQ_INSERT_TAIL.3
 MLINKS+=queue.3 CIRCLEQ_LAST.3 queue.3 CIRCLEQ_NEXT.3 queue.3 CIRCLEQ_PREV.3
 MLINKS+=queue.3 CIRCLEQ_REMOVE.3
-MLINKS+=stdarg.3 varargs.3 stdarg.3 va_arg.3 stdarg.3 va_copy.3 \
+MLINKS+=stdarg.3 va_arg.3 stdarg.3 va_copy.3 \
        stdarg.3 va_end.3 stdarg.3 va_start.3
 MLINKS+=dlfcn.3 dlopen.3 dlfcn.3 dlclose.3 dlfcn.3 dlsym.3 dlfcn.3 dlctl.3 \
        dlfcn.3 dlerror.3 dlfcn.3 dladdr.3
diff -r 12a718b48f7b -r 0773d67febd2 share/man/man3/stdarg.3
--- a/share/man/man3/stdarg.3   Mon Feb 04 19:07:47 2002 +0000
+++ b/share/man/man3/stdarg.3   Mon Feb 04 20:09:46 2002 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: stdarg.3,v 1.11 2002/02/04 18:27:38 kleink Exp $
+.\"    $NetBSD: stdarg.3,v 1.12 2002/02/04 20:09:46 kleink Exp $
 .\"
 .\" Copyright (c) 1990, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -42,7 +42,6 @@
 .Os
 .Sh NAME
 .Nm stdarg ,
-.Nm varargs ,
 .Nm va_arg  ,
 .Nm va_copy  ,
 .Nm va_end ,
diff -r 12a718b48f7b -r 0773d67febd2 share/man/man3/varargs.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man3/varargs.3  Mon Feb 04 20:09:46 2002 +0000
@@ -0,0 +1,206 @@
+.\"    $NetBSD: varargs.3,v 1.1 2002/02/04 20:09:46 kleink 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. 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.
+.\"
+.\"    From:
+.\"     (#)stdarg.3    8.1 (Berkeley) 6/5/93
+.\"     NetBSD: stdarg.3,v 1.11 2002/02/04 18:27:38 kleink Exp  
+.\"
+.Dd February 4, 2002
+.Dt VARARGS 3
+.Os
+.Sh NAME
+.Nm varargs
+.Nd variable argument lists
+.Sh SYNOPSIS
+.Fd #include <varargs.h>
+.Ft void
+.Fn va_start "va_list ap"
+.Ft type
+.Fn va_arg "va_list ap" type
+.Ft void
+.Fn va_end "va_list ap"
+.Sh DESCRIPTION
+.Bf -symbolic
+These historic interfaces are provided to support compilation of
+existing programs only.
+New code should use the
+.Xr stdarg 3
+interfaces.
+.Ef
+.Pp
+A function may be called with a varying number of arguments of varying
+types.
+The include file
+.Aq Pa varargs.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 name an argument
+.Fa va_alist ,
+which marks the start of the variable argument list,
+and which is naturally the last argument named.
+It is declared by
+.Fa va_dcl ,
+which should not be followed by a semicolon.
+The called function also 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
+It is possible for
+.Fa va_alist
+to be the only parameter to a function, resulting in it being possible
+for a function to have no fixed arguments preceeding the variable
+argument list.
+.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(fmt, va_alist)
+       char *fmt;
+       va_dcl
+{
+       va_list ap;
+       int d;
+       char c, *p, *s;
+
+       va_start(ap);
+       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 SEE ALSO
+.Xr stdarg 3
+.Sh STANDARDS
+These historic macros were replaced in
+.St -ansiC
+by the include file
+.Aq Pa stdarg.h ;
+see
+.Xr stdarg 3
+for its description.
+.Sh COMPATIBILITY
+These macros are
+.Em not
+compatible with the new macros they were replaced by.
+In particular, it is not possible for a
+.Em stdarg
+function to have no fixed arguments.