STDARG(3)

💖 stdarg(3) — variable argument lists 💖

okay bestie, so this is STDARG(3) from the Library Functions Manual, and honestly? it's giving "the one header that makes variadic functions not a total nightmare." come sit with me 🫶

---

✨ SYNOPSIS ✨

#include <stdarg.h>

void
va_start(va_list ap, last);

type
va_arg(va_list ap, type);

void
va_copy(va_list dest, va_list src);

void
va_end(va_list ap);

---

🌸 DESCRIPTION 🌸

okay so picture this: a function gets called with a varying number of arguments, and those arguments are of varying types. chaos? no bestie, it's a feature. the include file <stdarg.h> declares a type (va_list) and defines four macros for stepping through a list of arguments whose number and types are not known to the called function. iconic behavior honestly 👑

The called function must declare an object of type va_list which is used by the macros va_start(), va_arg(), va_copy(), and va_end(). like, all four of them are sharing custody of this one object.

The va_start() macro initializes ap for subsequent use by va_arg(), va_copy(), and va_end(), and must be called first. no skipping, it's the opening act. ✨

The parameter last is the name of the last parameter before the variable argument list, i.e., the last parameter of which the calling function knows the type. so like... the last one you can actually see.

🚨 Because the address of this parameter is used in the va_start() macro, it should not be declared as a register variable, or as a function or an array type. literally do not do it, it will not go well for you 💀

The va_arg() macro expands to an expression that has the type and value of the next argument in the call. The parameter ap is the va_list ap initialized by va_start() or va_copy(). Each call to va_arg() modifies ap so that the next call returns the next argument — it's like a little pointer goblin that eats one argument per call 🍓

The parameter type is a type name specified so that the type of a pointer to an object that has the specified type can be obtained simply by adding a * to type. iykyk.

💀 If there is no next argument, or if type is not compatible with the type of the actual next argument (as promoted according to the default argument promotions), random errors will occur. random. errors. not a vibe check you want to fail, fr fr.

The first use of the va_arg() macro after that of the va_start() macro returns the argument after last. Successive invocations return the values of the remaining arguments. one by one, slay by slay.

The va_copy() macro copies a variable argument list, previously initialized by va_start(), from src to dest. The state is preserved such that it is equivalent to calling va_start() with the same second argument used with src, and calling va_arg() the same number of times as called with src. so it's a genuine clone, not a "close enough" situation 💅

The va_end() macro cleans up any state associated with the variable argument list ap. it's the closing credits, the little bow on top 🎀

⚠️ Each invocation of va_start() or va_copy() must be paired with a corresponding invocation of va_end() in the same function. no cap, this is not optional.

---

🌈 RETURN VALUES 🌈

• The va_arg() macro returns the value of the next argument. 💖
• The va_start(), va_copy(), and va_end() macros return no value. they're above such things, they simply are.

---

🦋 EXAMPLES 🦋

The function foo takes a string of format characters and prints out the argument associated with each format character based on the type. honestly kind of a serve:

void foo(char *fmt, ...)
{
        va_list ap;
        int d;
        char c, *s;

        va_start(ap, fmt);
        while (*fmt)
                switch(*fmt++) {
                case 's':                       /* string */
                        s = va_arg(ap, char *);
                        printf("string %s\n", s);
                        break;
                case 'd':                       /* int */
                        d = va_arg(ap, int);
                        printf("int %d\n", d);
                        break;
                case 'c':                       /* char */
                        /* Note: char is promoted to int. */
                        c = va_arg(ap, int);
                        printf("char %c\n", c);
                        break;
                }
        va_end(ap);
}

did you catch the little /* Note: char is promoted to int. */ moment? that's the whole personality of this example right there 🙈

---

⭐ COMPATIBILITY ⭐

okay so listen — these macros are not compatible with the historic macros they replace. different era, different rules, no crossover episodes. periodt.

---

👑 STANDARDS 👑

The va_start(), va_arg(), va_copy(), and va_end() macros conform to ISO/IEC 9899:1999 ("ISO C99"). certified official, we love a standards-compliant queen ✨

---

🌸 HISTORY 🌸

• The va_start(), va_arg() and va_end() macros were introduced in ANSI X3.159-1989 ("ANSI C89"). the OGs 🫶
• The va_copy() macro was introduced in ISO/IEC 9899:1999 ("ISO C99"). the late arrival that still ate 💅

---

🍓 BUGS 🍓

so here's the sad part 😭 — unlike the varargs macros, the stdarg macros do not permit programmers to code a function with no fixed arguments. like, you need at least one named parameter to point last at. this problem generates work mainly when converting varargs code to stdarg code, but it also creates difficulties for variadic functions that wish to pass all of their arguments on to a function that takes a va_list argument, such as vfprintf(3). rude of it, honestly. it's giving "small limitation, big consequences" 💀

---

and that's the whole page, bestie! this version came to you courtesy of the Debian folks, dated October 18, 2024 — go forth and abuse va_list responsibly 🧚💜