diff options
Diffstat (limited to 'man-pages-posix-2017/man0p/stdarg.h.0p')
| -rw-r--r-- | man-pages-posix-2017/man0p/stdarg.h.0p | 226 |
1 files changed, 226 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man0p/stdarg.h.0p b/man-pages-posix-2017/man0p/stdarg.h.0p new file mode 100644 index 0000000..bfa482e --- /dev/null +++ b/man-pages-posix-2017/man0p/stdarg.h.0p @@ -0,0 +1,226 @@ +'\" et +.TH stdarg.h "0P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +stdarg.h +\(em handle variable argument list +.SH SYNOPSIS +.LP +.nf +#include <stdarg.h> +.P +void va_start(va_list \fIap\fP, \fIargN\fP); +void va_copy(va_list \fIdest\fP, va_list \fIsrc\fP); +\fItype\fP va_arg(va_list \fIap\fP, \fItype\fP); +void va_end(va_list \fIap\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +.IR <stdarg.h> +header shall contain a set of macros which allows portable functions +that accept variable argument lists to be written. Functions that have +variable argument lists (such as +\fIprintf\fR()) +but do not use these macros are inherently non-portable, as different +systems use different argument-passing conventions. +.P +The +.IR <stdarg.h> +header shall define the +.BR va_list +type for variables used to traverse the list. +.P +The +\fIva_start\fR() +macro is invoked to initialize +.IR ap +to the beginning of the list before any calls to +\fIva_arg\fR(). +.P +The +\fIva_copy\fR() +macro initializes +.IR dest +as a copy of +.IR src , +as if the +\fIva_start\fR() +macro had been applied to +.IR dest +followed by the same sequence of uses of the +\fIva_arg\fR() +macro as had previously been used to reach the present state of +.IR src . +Neither the +\fIva_copy\fR() +nor +\fIva_start\fR() +macro shall be invoked to reinitialize +.IR dest +without an intervening invocation of the +\fIva_end\fR() +macro for the same +.IR dest . +.P +The object +.IR ap +may be passed as an argument to another function; if that function +invokes the +\fIva_arg\fR() +macro with parameter +.IR ap , +the value of +.IR ap +in the calling function is unspecified and shall be passed to the +\fIva_end\fR() +macro prior to any further reference to +.IR ap . +The parameter +.IR argN +is the identifier of the rightmost parameter in the variable parameter +list in the function definition (the one just before the .\|.\|.). If +the parameter +.IR argN +is declared with the +.BR register +storage class, with a function type or array type, or with a type that +is not compatible with the type that results after application of the +default argument promotions, the behavior is undefined. +.P +The +\fIva_arg\fR() +macro shall return the next argument in the list pointed to by +.IR ap . +Each invocation of +\fIva_arg\fR() +modifies +.IR ap +so that the values of successive arguments are returned in turn. The +.IR type +parameter shall be a type name specified such that the type of a +pointer to an object that has the specified type can be obtained simply +by postfixing a +.BR '*' +to type. If there is no actual next argument, or if +.IR type +is not compatible with the type of the actual next argument (as +promoted according to the default argument promotions), the behavior is +undefined, except for the following cases: +.IP " *" 4 +One type is a signed integer type, the other type is the corresponding +unsigned integer type, and the value is representable in both types. +.IP " *" 4 +One type is a pointer to +.BR void +and the other is a pointer to a character type. +.IP " *" 4 +Both types are pointers. +.P +Different types can be mixed, but it is up to the routine to +know what type of argument is expected. +.P +The +\fIva_end\fR() +macro is used to clean up; it invalidates +.IR ap +for use (unless +\fIva_start\fR() +or +\fIva_copy\fR() +is invoked again). +.P +Each invocation of the +\fIva_start\fR() +and +\fIva_copy\fR() +macros shall be matched by a corresponding invocation of the +\fIva_end\fR() +macro in the same function. +.P +Multiple traversals, each bracketed by +\fIva_start\fR() +\&.\|.\|. +\fIva_end\fR(), +are possible. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +This example is a possible implementation of +\fIexecl\fR(): +.sp +.RS 4 +.nf + +#include <stdarg.h> +.P +#define MAXARGS 31 +.P +/* + * execl is called by + * execl(file, arg1, arg2, ..., (char *)(0)); + */ +int execl(const char *file, const char *args, ...) +{ + va_list ap; + char *array[MAXARGS +1]; + int argno = 0; +.P + va_start(ap, args); + while (args != 0 && argno < MAXARGS) + { + array[argno++] = args; + args = va_arg(ap, const char *); + } + array[argno] = (char *) 0; + va_end(ap); + return execv(file, array); +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +It is up to the calling routine to communicate to the called routine +how many arguments there are, since it is not always possible for the +called routine to determine this in any other way. For example, +\fIexecl\fR() +is passed a null pointer to signal the end of the list. The +\fIprintf\fR() +function can tell how many arguments are there by the +.IR format +argument. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The System Interfaces volume of POSIX.1\(hy2017, +.IR "\fIexec\fR\^", +.IR "\fIfprintf\fR\^(\|)" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |