install approved copyright notice

[unix-history] / usr / src / share / man / man3 / stdarg.3

diff --git a/usr/src/share/man/man3/stdarg.3 b/usr/src/share/man/man3/stdarg.3
index 11f28d5..779371d 100644 (file)
--- a/usr/src/share/man/man3/stdarg.3
+++ b/usr/src/share/man/man3/stdarg.3
@@ -1,24 +1,35 @@
-.\"    @(#)stdarg.3    4.1 (Berkeley) %G%
+.\"    @(#)stdarg.3    6.3 (Berkeley) %G%

 .\"
 .\"

-.TH VARARGS 3 
+.TH VARARGS 3  ""

 .AT 3
 .SH NAME
 varargs \- variable argument list
 .SH SYNOPSIS
 .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
+.B "#include <varargs.h>"
+.PP
+.I function\c
+.RB ( va_alist )
+.br
+.B va_dcl
+.br
+.B va_list
+.IR pvar ;
+.br
+.B va_start\c
+.RI ( pvar );
+.br
+f =
+.B va_arg\c
+.RI ( pvar ,
+.IR type );
+.br
+.B va_end\c
+.RI ( pvar );

 .SH DESCRIPTION
 .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))
+This set of macros provides a means of writing portable procedures that
+accept variable argument lists.
+Routines having 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
 that do not use varargs are inherently nonportable, since different
 machines use different argument passing conventions.
 .PP


@@ -26,40 +37,57 @@ machines use different argument passing conventions.
 is used in a function header to declare a variable argument list.
 .PP
 .B va_dcl
 is used in a function header to declare a variable argument list.
 .PP
 .B va_dcl

-is a declaration for \fBva_alist\fP.
+is a declaration for
+.BR va_alist .

 Note that there is no semicolon after
 .B va_dcl.
 .PP
 .B va_list
 is a type which can be used for the variable
 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,
+.IR pvar ,

 which is used to traverse the list.
 One such variable must always be declared.
 .PP
 which is used to traverse the list.
 One such variable must always be declared.
 .PP

-.B va_start
+.B va_start\c

 .RI (pvar)
 is called to initialize
 .I pvar
 to the beginning of the list.
 .PP
 .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
+.B va_arg\c
+.RI ( pvar ,
+.IR type )
+will return the next argument in the list pointed to by

 .IR pvar .
 .I Type
 .IR pvar .
 .I Type

-is the type the argument is expected to be.
+is the type to which the expected argument will be converted
+when passed as an argument.
+In standard C, arguments that are
+.B char
+or
+.B short
+should be accessed as
+.BR int ,
+.B "unsigned char
+or
+.B "unsigned short
+are converted to
+.BR "unsigned int" ,
+and
+.B float
+arguments are converted to
+.BR double .

 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
 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
+.B va_end\c

 .RI ( pvar )
 is used to finish up.
 .PP
 .RI ( pvar )
 is used to finish up.
 .PP

-Multiple traversals, each bracketted by
+Multiple traversals, each bracketed by

 .B va_start
 .B va_start

-\&..
+\&...

 .B va_end,
 are possible.
 .SH EXAMPLE
 .B va_end,
 are possible.
 .SH EXAMPLE


@@ -88,4 +116,17 @@ stack frame.  For example,
 .I execl
 passes a 0 to signal the end of the list.
 .I Printf
 .I execl
 passes a 0 to signal the end of the list.
 .I Printf

-can tell how many arguments are there by the format.
+can tell how many arguments are supposed to be there by the format.
+.PP
+The macros
+.I va_start
+and
+.I va_end
+may be arbitrarily complex;
+for example,
+.I va_start
+might contain an opening brace,
+which is closed by a matching brace in
+.IR va_end .
+Thus, they should only be used where they could
+be placed within a single complex statement.