README.md
20cde316
 # mulle-vararg
 
b0c7677f
 A variable argument passing scheme written in C (C11). It's an alternative
a38651ff
 to
 [stdarg](//en.wikipedia.org/wiki/Stdarg.h) or
 [varargs](//pubs.opengroup.org/onlinepubs/7908799/xsh/varargs.h.html),
 but not compatible with either.
b0c7677f
 
f786b587
 
 Fork      |  Build Status | Release Version
 ----------|---------------|-----------------------------------
 [Mulle kybernetiK](//github.com/mulle-nat/mulle-vararg) | [![Build Status](https://travis-ci.org/mulle-nat/mulle-vararg.svg?branch=release)](https://travis-ci.org/mulle-nat/mulle-vararg) | ![Mulle kybernetiK tag](https://img.shields.io/github/tag/mulle-nat/mulle-vararg.svg) [![Build Status](https://travis-ci.org/mulle-nat/mulle-vararg.svg?branch=release)](https://travis-ci.org/mulle-nat/mulle-vararg)
3dc64fc2
 
95c203dd
 ## Install
3dc64fc2
 
95c203dd
 Install the prerequisites first:
b0c7677f
 
95c203dd
 | Prerequisites                                           |
 |---------------------------------------------------------|
 | [mulle-c11](//github.com/mulle-c/mulle-c11)             |
ba024d0f
 
b0c7677f
 
95c203dd
 Then build and install
b0c7677f
 
95c203dd
 ```
 mkdir build 2> /dev/null
 (
    cd build ;
    cmake .. ;
    make install
 )
 ```
 
 Or let [mulle-sde](//github.com/mulle-sde) do it all for you.
7ed80384
 
2edbc8d2
 
 ## How it works
 
7ed80384
 **mulle-vararg** assumes that the arguments are not layed out in stack
 alignment fashion but like in a struct. The C promotion rules are still
 observed though.
2edbc8d2
 
7ed80384
 > Remember the C argument promotion rules are
 >
 > 1. char and short to int/unsigned int
 > 2. float to double
 >
2edbc8d2
 
b0c7677f
 Let's assume there is a compiler that uses **mulle-vararg** for variable
 arguments. It collects **all** function parameters and packs them into a struct,
 then passes this struct to the function.
2edbc8d2
 
7ed80384
 A **printf** function being being called like this:
2edbc8d2
 
 ```
7ed80384
 printf( "%d %f %lld\n", (char) 'x', (float) 0.2, 1848LL;
2edbc8d2
 ```
 
b0c7677f
 would get its arguments embedded in a struct like this
2edbc8d2
 
 ```
 struct
 {
7ed80384
    char    *format;
6065160a
    struct
2edbc8d2
    {
7ed80384
       int         value1;     // standard char -> int promotion
       double      value2;     // standard float -> double promotion
2edbc8d2
       long long   value3;
    } varargs;
 } _param;
 ```
 
7ed80384
 **mulle-vararg** provides the necessary functions to read such a struct. It has
 no code to create it.
 
b0c7677f
 
95c203dd
 #### Advantages
7ed80384
 
95c203dd
 * Easy to write in C, does not need compiler ABI internals to construct or
 read. You don't need [libffi](//sourceware.org/libffi/) or some such.
 * Cheap forwarding to other functions.
7ed80384
 
 
95c203dd
 #### Disadvantages
7ed80384
 
95c203dd
 * Not compatible with `<stdarg.h>`
7ed80384
 
 
 
95c203dd
 ## API
7ed80384
 
95c203dd
 * [Vararg](dox/API_VARARG.md)
7ed80384
 
 ### Platforms and Compilers
 
 All platforms and compilers supported by
95c203dd
 [mulle-c11](//github.com/mulle-c/mulle-c11)
7ed80384
 
286b3d8e
 ## Author
 
 [Nat!](//www.mulle-kybernetik.com/weblog) for
 [Mulle kybernetiK](//www.mulle-kybernetik.com) and
 [Codeon GmbH](//www.codeon.de)