### 4.2 API for embedding ¶

Instead of letting `codger` generate simple wrapper functions for you, you can omit the `PROTOTYPE` comment, and write `Y_my_func` yourself. Its prototype is

    extern void Y_my_func(int argc);

The `argc` argument is the count of the number of items on the stack containing the arguments the interpreter is passing to `Y_my_func`. This would be simply the number of arguments the caller is passing to your function, were it not for the possibility of keyword arguments. Each actual keyword argument takes two spaces on the stack – one for the name of the keyword and a second for its value. If your function does not accept keywords, you can ignore the distinction between `argc` and the number of arguments being passed to your function.

When your function exits, whatever you leave on top of the stack becomes its return value. This section explains the programming interface (or API) which permits you to get your arguments off the stack, push new items onto the stack, set or get global variable values, and otherwise interact with the yorick interpreter. All of these functions are declared in the `yapi.h` header, which your C (or C++) source file should include.

The following examples do not illustrate all of the functions in `yapi.h`; you need to read the header file itslef for a comprehensive list. For more examples of `yapi.h` usage, read the yorick source file `yorick/ystr.c`.