stdarg.html 2.4 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879
  1. <html>
  2. <head>
  3. <title>stdarg</title>
  4. <body bgcolor=#ffffff>
  5. <h2 align=center>stdarg</h2>
  6. <h4 align=center>OS/161 Reference Manual</h4>
  7. <h3>Name</h3>
  8. stdarg - handle functions with variable arguments
  9. <h3>Library</h3>
  10. Standard C Library (libc, -lc)
  11. <h3>Synopsis</h3>
  12. #include &lt;stdarg.h&gt;<br>
  13. <br>
  14. va_start(va_list <em>ap</em>, <em>start-argument</em>);<br>
  15. <br>
  16. va_end(va_list <em>ap</em>);<br>
  17. <br>
  18. <em>type</em><br>
  19. va_arg(va_list <em>ap</em>, <em>type</em>);<br>
  20. <br>
  21. va_copy(va_list <em>dest</em>, va_list <em>src</em>);<br>
  22. <h3>Description</h3>
  23. Functions where the number of arguments is not fixed at compile time
  24. can be written using the stdarg facility. This provides a type,
  25. va_list, and the macros listed above, which allow iterating through
  26. the arguments.
  27. <p>
  28. va_start initializes a va_list <em>ap</em> to point to the current
  29. function's arguments. The <em>start-argument</em> argument should be
  30. the name of the last fixed parameter in the calling sequence.
  31. <p>
  32. va_end cleans up a va_list once it is no longer needed. While failure
  33. to use va_end may have no effect on some architectures (in fact, in
  34. some cases va_end does nothing at all) on other architectures it may
  35. be fatal.
  36. <p>
  37. va_arg retrieves the next argument, which is presumed to be of type
  38. <em>type</em>. The function must have some way to determine what types
  39. to expect, and how many arguments, as this information cannot be
  40. extracted from the argument list itself. To rewind, use va_end and
  41. then va_start again.
  42. <p>
  43. Remember that default C argument promotions occur when passing the
  44. variable arguments. There is no run-time checking of any kind, and
  45. little to no compile-time checking: if you retrieve a type different
  46. from that which was passed using va_arg, you will silently get garbage
  47. for that and all subsequent arguments.
  48. <p>
  49. va_copy assigns a copy of <em>src</em> to <em>dest</em>. Subsequent
  50. operations on either will not affect the other.
  51. <p>
  52. <h3>Restrictions</h3>
  53. Because the va_list is not necessarily a simple type, but may involve
  54. pointers to state maintained elsewhere, it is not necessarily a simple
  55. value. Thus, assigning va_lists to each other with `=', memcpy, or the
  56. like, or passing them to functions, may not give multiple independent
  57. objects. When in doubt, use va_copy, or invoke va_start multiple
  58. times.
  59. <p>
  60. <h3>Return Values</h3>
  61. va_start, va_end, and va_copy do not return anything. va_arg returns
  62. the value of the requested argument.
  63. </body>
  64. </html>