manual page distributed with 4.1BSD

SCCS-vsn: share/man/man3/stdarg.3 4.1

diff --git a/usr/src/share/man/man3/stdarg.3 b/usr/src/share/man/man3/stdarg.3
new file mode 100644 (file)
index 0000000..11f28d5
--- /dev/null
+++ b/usr/src/share/man/man3/stdarg.3
@@ -0,0 +1,91 @@
+.\"    @(#)stdarg.3    4.1 (Berkeley) %G%
+.\"
+.TH VARARGS 3 
+.AT 3
+.SH NAME
+varargs \- variable argument list
+.SH SYNOPSIS
+.nf
+#include <varargs.h>
+\fIfunction\fR(\fBva_alist\fR)
+\fBva_dcl
+va_list \fIpvar\fR;
+\fBva_start\fR(\fIpvar\fR);
+f = \fBva_arg\fR(\fIpvar\fR, \fItype\fR);
+\fBva_end\fR(\fIpvar\fR);
+.fi
+.SH DESCRIPTION
+This set of macros allows portable procedures that accept variable
+argument lists to be written.
+Routines which have variable argument lists (such as
+.IR printf(3))
+that do not use varargs are inherently nonportable, since different
+machines use different argument passing conventions.
+.PP
+.B va_alist
+is used in a function header to declare a variable argument list.
+.PP
+.B va_dcl
+is a declaration for \fBva_alist\fP.
+Note that there is no semicolon after
+.B va_dcl.
+.PP
+.B va_list
+is a type which can be used for the variable
+.I pvar,
+which is used to traverse the list.
+One such variable must always be declared.
+.PP
+.B va_start
+.RI (pvar)
+is called to initialize
+.I pvar
+to the beginning of the list.
+.PP
+.B va_arg
+.RI ( pvar , type )
+will return the next argument in the list
+pointed to by
+.IR pvar .
+.I Type
+is the type the argument is expected to be.
+Different types can be mixed, but it is up
+to the routine to know what type of argument is
+expected, since it cannot be determined at runtime.
+.PP
+.B va_end
+.RI ( pvar )
+is used to finish up.
+.PP
+Multiple traversals, each bracketted by
+.B va_start
+\&..
+.B va_end,
+are possible.
+.SH EXAMPLE
+.nf
+       \fB#include\fP <varargs.h>
+       execl(\fBva_alist\fP)
+       \fBva_dcl\fP
+       {
+               \fBva_list\fP ap;
+               \fBchar\fP *file;
+               \fBchar\fP *args[100];
+               \fBint\fP argno = 0;
+
+               \fBva_start\fP(ap);
+               file = \fBva_arg(ap, \fBchar\fP *);
+               \fBwhile\fP (args[argno++] = \fBva_arg\fP(ap, \fBchar\fP *))
+                       \fB;\fP
+               \fBva_end\fP(ap);
+               \fBreturn\fP execv(file, args);
+       }
+.fi
+.SH BUGS
+It is up to the calling routine to determine how many arguments
+there are, since it is not possible to determine this from the
+stack frame.  For example,
+.I execl
+passes a 0 to signal the end of the list.
+.I Printf
+can tell how many arguments are there by the format.