logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

stdarg.h.0p (6083B)


  1. '\" et
  2. .TH stdarg.h "0P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. stdarg.h
  12. \(em handle variable argument list
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <stdarg.h>
  17. .P
  18. void va_start(va_list \fIap\fP, \fIargN\fP);
  19. void va_copy(va_list \fIdest\fP, va_list \fIsrc\fP);
  20. \fItype\fP va_arg(va_list \fIap\fP, \fItype\fP);
  21. void va_end(va_list \fIap\fP);
  22. .fi
  23. .SH DESCRIPTION
  24. The functionality described on this reference page is aligned with the
  25. ISO\ C standard. Any conflict between the requirements described here and the
  26. ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
  27. .P
  28. The
  29. .IR <stdarg.h>
  30. header shall contain a set of macros which allows portable functions
  31. that accept variable argument lists to be written. Functions that have
  32. variable argument lists (such as
  33. \fIprintf\fR())
  34. but do not use these macros are inherently non-portable, as different
  35. systems use different argument-passing conventions.
  36. .P
  37. The
  38. .IR <stdarg.h>
  39. header shall define the
  40. .BR va_list
  41. type for variables used to traverse the list.
  42. .P
  43. The
  44. \fIva_start\fR()
  45. macro is invoked to initialize
  46. .IR ap
  47. to the beginning of the list before any calls to
  48. \fIva_arg\fR().
  49. .P
  50. The
  51. \fIva_copy\fR()
  52. macro initializes
  53. .IR dest
  54. as a copy of
  55. .IR src ,
  56. as if the
  57. \fIva_start\fR()
  58. macro had been applied to
  59. .IR dest
  60. followed by the same sequence of uses of the
  61. \fIva_arg\fR()
  62. macro as had previously been used to reach the present state of
  63. .IR src .
  64. Neither the
  65. \fIva_copy\fR()
  66. nor
  67. \fIva_start\fR()
  68. macro shall be invoked to reinitialize
  69. .IR dest
  70. without an intervening invocation of the
  71. \fIva_end\fR()
  72. macro for the same
  73. .IR dest .
  74. .P
  75. The object
  76. .IR ap
  77. may be passed as an argument to another function; if that function
  78. invokes the
  79. \fIva_arg\fR()
  80. macro with parameter
  81. .IR ap ,
  82. the value of
  83. .IR ap
  84. in the calling function is unspecified and shall be passed to the
  85. \fIva_end\fR()
  86. macro prior to any further reference to
  87. .IR ap .
  88. The parameter
  89. .IR argN
  90. is the identifier of the rightmost parameter in the variable parameter
  91. list in the function definition (the one just before the .\|.\|.). If
  92. the parameter
  93. .IR argN
  94. is declared with the
  95. .BR register
  96. storage class, with a function type or array type, or with a type that
  97. is not compatible with the type that results after application of the
  98. default argument promotions, the behavior is undefined.
  99. .P
  100. The
  101. \fIva_arg\fR()
  102. macro shall return the next argument in the list pointed to by
  103. .IR ap .
  104. Each invocation of
  105. \fIva_arg\fR()
  106. modifies
  107. .IR ap
  108. so that the values of successive arguments are returned in turn. The
  109. .IR type
  110. parameter shall be a type name specified such that the type of a
  111. pointer to an object that has the specified type can be obtained simply
  112. by postfixing a
  113. .BR '*'
  114. to type. If there is no actual next argument, or if
  115. .IR type
  116. is not compatible with the type of the actual next argument (as
  117. promoted according to the default argument promotions), the behavior is
  118. undefined, except for the following cases:
  119. .IP " *" 4
  120. One type is a signed integer type, the other type is the corresponding
  121. unsigned integer type, and the value is representable in both types.
  122. .IP " *" 4
  123. One type is a pointer to
  124. .BR void
  125. and the other is a pointer to a character type.
  126. .IP " *" 4
  127. Both types are pointers.
  128. .P
  129. Different types can be mixed, but it is up to the routine to
  130. know what type of argument is expected.
  131. .P
  132. The
  133. \fIva_end\fR()
  134. macro is used to clean up; it invalidates
  135. .IR ap
  136. for use (unless
  137. \fIva_start\fR()
  138. or
  139. \fIva_copy\fR()
  140. is invoked again).
  141. .P
  142. Each invocation of the
  143. \fIva_start\fR()
  144. and
  145. \fIva_copy\fR()
  146. macros shall be matched by a corresponding invocation of the
  147. \fIva_end\fR()
  148. macro in the same function.
  149. .P
  150. Multiple traversals, each bracketed by
  151. \fIva_start\fR()
  152. \&.\|.\|.
  153. \fIva_end\fR(),
  154. are possible.
  155. .LP
  156. .IR "The following sections are informative."
  157. .SH "EXAMPLES"
  158. This example is a possible implementation of
  159. \fIexecl\fR():
  160. .sp
  161. .RS 4
  162. .nf
  163. #include <stdarg.h>
  164. .P
  165. #define MAXARGS 31
  166. .P
  167. /*
  168. * execl is called by
  169. * execl(file, arg1, arg2, ..., (char *)(0));
  170. */
  171. int execl(const char *file, const char *args, ...)
  172. {
  173. va_list ap;
  174. char *array[MAXARGS +1];
  175. int argno = 0;
  176. .P
  177. va_start(ap, args);
  178. while (args != 0 && argno < MAXARGS)
  179. {
  180. array[argno++] = args;
  181. args = va_arg(ap, const char *);
  182. }
  183. array[argno] = (char *) 0;
  184. va_end(ap);
  185. return execv(file, array);
  186. }
  187. .fi
  188. .P
  189. .RE
  190. .SH "APPLICATION USAGE"
  191. It is up to the calling routine to communicate to the called routine
  192. how many arguments there are, since it is not always possible for the
  193. called routine to determine this in any other way. For example,
  194. \fIexecl\fR()
  195. is passed a null pointer to signal the end of the list. The
  196. \fIprintf\fR()
  197. function can tell how many arguments are there by the
  198. .IR format
  199. argument.
  200. .SH RATIONALE
  201. None.
  202. .SH "FUTURE DIRECTIONS"
  203. None.
  204. .SH "SEE ALSO"
  205. The System Interfaces volume of POSIX.1\(hy2017,
  206. .IR "\fIexec\fR\^",
  207. .IR "\fIfprintf\fR\^(\|)"
  208. .\"
  209. .SH COPYRIGHT
  210. Portions of this text are reprinted and reproduced in electronic form
  211. from IEEE Std 1003.1-2017, Standard for Information Technology
  212. -- Portable Operating System Interface (POSIX), The Open Group Base
  213. Specifications Issue 7, 2018 Edition,
  214. Copyright (C) 2018 by the Institute of
  215. Electrical and Electronics Engineers, Inc and The Open Group.
  216. In the event of any discrepancy between this version and the original IEEE and
  217. The Open Group Standard, the original IEEE and The Open Group Standard
  218. is the referee document. The original Standard can be obtained online at
  219. http://www.opengroup.org/unix/online.html .
  220. .PP
  221. Any typographical or formatting errors that appear
  222. in this page are most likely
  223. to have been introduced during the conversion of the source files to
  224. man page format. To report such errors, see
  225. https://www.kernel.org/doc/man-pages/reporting_bugs.html .