The C Subset¶
The header describing an FFI boundary is written in a subset of C99: what can be described equivalently in C, C++, Python, Rust and Zig. Every place a header steps outside it is reported, by the rule it breaks, see Rules. This page describes the subset, and why.
What is in it¶
- Types
void,bool,char,signed char,unsigned char,short,int,long,long longand their unsigned forms,float,double, the fixed-width integers of<stdint.h>,intptr_t,uintptr_t,size_t,ssize_tandptrdiff_t; pointers to any of these, and fixed-length arrays of them, of any dimension.- Records
structandunion, each with a tag and defined at the top level. A record declared but never defined is opaque, a handle used through pointers. A typedef of a record of its own name,typedef struct foo foo;, is that record; one of another type,typedef struct foo *foo;, which no binding could declare beside the record, is reported, and its type used in its place.- Enumerations
enum, with a tag, to name and document values.- Functions
Declarations of functions, with named parameters, taking and returning the types above, records by pointer.
- Function pointers
typedef’d, with named parameters, for callbacks.- Constants
#defineof a string literal or an integer constant expression.- Headers
#includeof the standard headers above. What another header declares is outside the boundary: a type from one is reported as external-type.
An API of several headers¶
A library may describe its API in more than one header, such as an umbrella header and one header per part of the API. The headers given to yace are the API: it parses them together, as one model, and generates one binding of it per target. What they declare of each other is internal to the API, and what any other header declares, those of the system included, is external.
The headers given, in the order given, compile together as one unit; that set,
not each header in it, is what has to be self-contained. yace includes
<stdbool.h>, <stddef.h> and <stdint.h> before them, so a header
may use the standard types those declare without including them, and a header
may use what one given before it declares without including it. The
umbrella header of a library often does this on behalf of its parts, and the
parts can then be given in its order. A set that does not compile, such as
one given in an order where a type is used before the header declaring it, is
reported as parse-error. Of the system headers, only the types listed above
may appear in the API; ssize_t, from <sys/types.h>, is the one a header
includes itself.
A set whose umbrella header includes other system headers on behalf of its
parts, such as <stdio.h>, can be given them with --prelude, once for
each, as --prelude stdio.h. They are included after the standard headers
above and before the set, as the umbrella would, and the IR records them in its
meta, so that the generated C header includes them too. What they declare is
not part of the API: a type of theirs that the API uses, such as FILE, is
still reported as external-type.
For example, of a library whose headers are in include/:
yace --emit python rust -I include include/libfoo.h include/libfoo_*.h
Without --meta, the IR and the status are named by the first header given,
libfoo.yaml and libfoo.status. With a meta that gives the prefix
foo, they are foo.yaml and foo.status. A header left out, such as
one of internal helpers, is not part of the API; a type from it is external.
Records¶
Records are how data crosses the boundary. C has many ways of defining them; only some of them bind well. Nested anonymous records, for example:
struct delivery {
int carrier;
struct {
int x;
int y;
int z;
} location;
};
are valid C, and common, but other languages have no anonymous record types. Binding generators work around it each in its own way, typically by hoisting the nested record out under an invented name. yace does the same, so that a header outside the subset can still be used, but reports it: the record should be defined, named and documented in the header, at the source, rather than renamed by each generator:
/**
* Where a delivery goes
*/
struct delivery_location {
int x; ///< And the members...
int y;
int z;
};
/**
* A delivery
*/
struct delivery {
int carrier;
struct delivery_location location;
};
Bit-fields are left out for the same reason: Rust has none, and the packed structs of Zig are not laid out as C bit-fields are. Use a fixed-width integer and name its parts with masks, as a field of bits, below.
Records cross the boundary by pointer. Passed or returned by value, they depend on the calling convention of each platform for records, which other languages implement to varying degrees. How layout and calling conventions bear on a binding, and what yace does with records by value, bit-fields and packed records, is in Background.
Fields of bits¶
A field of bits, such as a status of a device, is an unsigned integer of the
width the field has, and each of its parts is named by a mask: an object-like
#define of the part’s bits in their place. The integer’s doc names the
prefix of its masks, and each mask’s doc ends in which bits of which field it
is:
/**
* A status
*/
struct foo_status {
uint16_t code; ///< Status code, see FOO_STATUS_CODE_*
};
/** Generic, command specific or media error; bits 2:0 of 'code' */
#define FOO_STATUS_CODE_TYPE 0x7
/** Whether there is more in the log; bit 15 of 'code' */
#define FOO_STATUS_CODE_MORE 0x8000
The masks are named <PREFIX>_<STRUCT>_<FIELD>_<PART>, and follow the
record, in the order of its fields and of the bits within each. yace links
each mask to its field in the IR, as yace.ir.decls.Mask, and the
targets use it.
The link is declared by the doc comments, not by a tag of yace’s own. Both ends
of it are written by the author of the header, the field naming the prefix of
its masks and each mask naming its field and its bits, so nothing is inferred
from a name alone, and the convention is the one a header for C would follow
anyway, as xNVMe’s do. A tag would say again what the two comments already say.
What remains is to check that they agree, and every way they may not is
reported by the bit-mask rule, the mask left unlinked: a mask whose name is
under the prefix of no field of that name, or of more than one; a prefix that
does not end in the field’s name; a field that is not an unsigned integer; a
mask of no bits, of bits that are not contiguous, or wider than the field; a
doc whose bits are not those of the value; masks of a field that overlap; a
part that is no identifier, or whose accessor, <field>_<part>, the record
has already; and a #define under the prefix of a field of bits whose doc
does not say which bits it is. A field whose see <PREFIX>_* names constants
none of which say which bits they are, such as the values of an opcode, is not
a field of bits.
Integers and char¶
The width of int, long and the others, and whether char is signed,
are up to the platform. Each target maps them to its language’s C types, such
as c_int and c_char in Rust, so the bindings have the widths of the
platform, as C does. Where a width matters to the API, say so with the
fixed-width integers.
Functions and enums¶
Do not pass or return an enum. C does not restrict an enum to its values; a
function declared to return enum foo_state can return any integer, so the
declaration promises a type safety C does not give. Take or return an integer,
and document the enum it takes its values from:
/**
* Upper and lower threshold
*/
enum foo_threshold {
FOO_THRESHOLD_UPPER = 200, ///< Upper limit
FOO_THRESHOLD_LOWER = 100, ///< Lower limit
};
The enum names and documents the values, and gives other languages a place to put them.
Variadic functions are outside the subset: calling them is not portable across
languages, see Background. A variadic function is reported, and
recorded in the IR as variadic. The C API, the Cython .pxd of the
Python target, and the raw layers of Rust and Zig declare it. The Python module
and the Go package do not bind it, and no idiomatic layer wraps it.
Inline and static functions, function-like macros and static assertions are used by the C compiler only, and are not part of the boundary. They are skipped and reported as notes, which do not fail the run. Variables are skipped too, and reported as diagnostics, since a variable has a symbol that other languages cannot bind. None of them is in the IR.
typedef¶
Only function pointers may be typedef’d:
typedef int (*binop_func)(void *ctx, int x, int y);
so that functions taking callbacks are readable:
/**
* Apply 'op' to 'a' and 'b'
*
* @lifetime op call
*/
int
apply_func(binop_func op, void *ctx, int a, int b);
A function pointer typedef must end in _cb, _callback, _fn,
_fun, _func or _function, as nothing else tells a reader that the
name is a function pointer, and its parameters must be named, as the names, and
their documentation, are what tell a reader how it is called.
Other typedefs only give a type another name. That name hides the type it
stands for, and is not a new type: it gives no more type safety than the type
itself. Refer to types by their own names. Do not name types with the _t
suffix either; it is reserved by POSIX.
What C cannot say¶
C declares types, not intent. int foo_open(const char *name, struct foo_handle
**handle) does not say that handle is written rather than read, that the
handle must later be given to foo_close(), or that a negative return is an
errno. A binding that only calls C needs none of this; one that is idiomatic in
its language needs all of it: to return what is written, to raise or return an
error, and to release the handle when it goes out of scope.
Three rules settle what a convention can settle:
A returned string is
const char *, and borrowed: it belongs to the library, or to the handle it came from, and is never the caller’s to free.A returned
constpointer to a record is a view: bindings may hand back a copy. Withoutconstit is an object the caller may write, and given to other functions by its address, so bindings return the pointer.A callback takes exactly one
void *, its context, and a function taking a callback takes its context as the next parameter, so that other languages can pass a closure.
The rest is said in the Doxygen comment of the function:
@param[in],@param[out],@param[in,out]Doxygen’s own: whether the function reads what a pointer points to, writes it, or both. Without one, it is read.
@arrparam name textAs
@param, for an array, with a direction as@paramhas. Its length is the unsigned integer<name>_len; of an[out]array, that is the capacity, which the caller gives. An[out]array may also have a count of the elements the function wrote, the[out]pointer to an unsigned integer<name>_nwritten; the bindings return the array cut to that count. Where a parameter is named otherwise,@len_at{length}and@nwritten_at{count}in the text name it.@recparam name textAs
@param, for a record of arguments, as the record arguments pattern below describes:nameis an[in]pointer to a const struct, and its size is thesize_t<name>_nbytes, or the parameter that@nbytes_at{size}in the text names. The function’s name ends in_sized, and the headers define a static inline function of the name without the suffix, which passessizeof; yace checks that the function exists, not what it passes.@nullable name ...The named pointers may be NULL;
returnnames what the function returns. Every other pointer must not be.@errnoThe function returns a negative errno on failure, and zero or more on success.
@errno partialsays that the function writes its[out]parameters also when it fails, so that what it wrote is not lost: the error of each binding carries what the call returns when it succeeds. The function returnsint, since a count it returned would be lost to the errno, and has an[out]parameter, and no[out]handle, since nobody owns a handle from a failed call.@destroys nameThe function releases the handle given as
name, its only parameter. An opaque record that a function creates through an[out]pointer must have a function that destroys it.@lifetime callback call|once|handle ...How long the library may invoke the callback, one for every callback parameter:
call, only during the call;once, at most once, after it;handle, until the handle is destroyed. Nothing in C says which, so it is a promise the author of the header makes, and the bindings keep the closure exactly as long as it says. A callback without one breaks the callback-lifetime rule, and is bound only as a raw function pointer. Thevoid *after the callback, its context, is no@arrparam. See Callback lifetimes, which describes each with the example library’s callbacks.@nobindThe function is not bound in any language. yace leaves it out before reading its types, so they may be outside the subset, such as the
FILE *of a printer of the library’s own, which C callers use and the bindings replace. A static or inline function with the tag is left out without being reported.
For example:
/**
* Open a handle holding no points
*
* @param[in] name Name of the handle, copied
* @param[out] handle Set to the handle opened
*
* @return 0 on success, -EINVAL when 'name' or 'handle' is NULL
*
* @errno
*/
int
foo_open(const char *name, struct foo_handle **handle);
/**
* Take the points that are ready, as many as fit
*
* @param handle The handle
* @arrparam[out] points The points taken @len_at{max} @nwritten_at{taken}
* @param max The number of points that 'points' has room for
* @param[out] taken Set to the number of points taken, also on failure
*
* @return 0 on success, a negative errno on failure
*
* @errno partial
*/
int
foo_take(struct foo_handle *handle, struct foo_point *points, uint32_t max,
uint32_t *taken);
/**
* Close a handle
*
* @param handle The handle to close, NULL is ignored
*
* @nullable handle
* @destroys handle
*/
void
foo_close(struct foo_handle *handle);
Named points_len and points_nwritten, the parameters of foo_take()
would need neither @len_at nor @nwritten_at. Where a parameter has
the conventional name, a reference naming another is reported, as the name
would mislead. So is a reference outside the text of an @arrparam or
@recparam, one without its parameter in braces, one given twice, and a
parameter documented by @arrparam or @recparam and another tag. In the
comment of anything but a function, the references, @arrparam and
@recparam are reported too.
Doxygen reads @arrparam and @recparam as @param, and the
references inline, through aliases:
ALIASES += arrparam=@param
ALIASES += recparam=@param
ALIASES += "len_at{1}=(length: @p \1)"
ALIASES += "nwritten_at{1}=(count written: @p \1)"
ALIASES += "nbytes_at{1}=(size: @p \1)"
Every tag is checked: one naming a parameter that does not exist, or one that
does not fit it, such as @errno on a function returning a pointer, is
reported by the annotation rule. What the tags say is recorded in the IR, on
the function and its parameters; see yace.ir.semantics.
Patterns¶
The rules and tags above describe a function one parameter at a time. Some functions combine them into a recurring shape, a pattern, which each binding turns into the idiom of its language. Each pattern is listed with its C shape and what the bindings make of it.
- Handle
An opaque record, created by a function that writes it through an
[out]pointer to a pointer, and released by the function that@destroysit. The functions taking it as their first parameter are its methods. The bindings make it a type that owns the pointer and releases it when it goes out of scope.- Callback and context
A pointer to a function taking one
void *, followed by thatvoid *, its context, with a@lifetime. The bindings take a closure, and pass the context themselves.- Array and length
An
@arrparam, and its length. An array read is given as a sequence, and its length is not given. Of an[out]array, the length is the capacity, and the count written, where there is one, cuts the array the bindings return.- Record arguments
A function taking its arguments as a record, so that arguments can be added without changing its signature:
/** * ... * @param handle The handle * @recparam args The arguments, see ::foo_read_args * @param args_nbytes The size of the record the program was built with */ int foo_read_sized(struct foo_handle *handle, const struct foo_read_args *args, size_t args_nbytes); static inline int foo_read(struct foo_handle *handle, const struct foo_read_args *args) { return foo_read_sized(handle, args, sizeof(*args)); }
The library compares
args_nbyteswith the size of its own record to tell a program built against an older header, whose record is smaller, and reads the members that record lacks as zero. So members are only added at the end of the record, and zero is the default of every member. C callers call the static inline function, which passes the size. The bindings cannot call it, so they pass the size of the record’s type themselves, and take its name:handle.read(args). A function may take more than one record, each with a size of its own, anywhere among its parameters.- Buffer
Memory for the library’s use that the library allocates, by functions named for it:
void *foo_buf_alloc(const struct foo_handle *handle, size_t nbytes); void *foo_buf_realloc(const struct foo_handle *handle, void *buf, size_t nbytes); void foo_buf_free(const struct foo_handle *handle, void *buf);
<stem>_allocreturns avoid *tosize_t nbytesbytes.<stem>_freefrees it, taking it as its onevoid *.<stem>_realloc, where there is one, resizes it, taking it andnbytes. The other parameters of the two are named and typed as parameters of<stem>_alloc, and the bindings pass them the values the buffer was allocated with. An allocation without a<stem>_freebreaks the buffer-lifecycle rule. The bindings make the buffer a type that owns the memory and frees it when it goes out of scope. What<stem>_allocwrites to an[out]parameter, such as a physical address, is returned with the buffer, as for any function. The bindings cannot pass<stem>_reallocan[out]parameter again, as they have no place to return it, so such a buffer cannot be resized, and<stem>_reallocis left to the raw layer, as it frees the memory the buffer owns.- Registration
Memory of the caller’s that the library is to use, such as memory a device reads and writes directly, by functions named for it:
int foo_buf_register(const struct foo_handle *handle, void *vaddr, size_t nbytes); int foo_buf_unregister(const struct foo_handle *handle, void *vaddr);
<stem>_register, documented@errno, registerssize_t nbytesbytes at its onevoid *, until<stem>_unregistertakes that address. The other parameters of<stem>_unregisterare named and typed as parameters of<stem>_register. A registration without an<stem>_unregister, or without@errno, breaks the buffer-lifecycle rule. The bindings take the memory as an object of their language, keep it alive while it is registered, and unregister it when the registration goes out of scope.
Documentation¶
Every declaration on the boundary must be documented, with a Doxygen comment
before it, or a ///< after it, so the bindings generated are documented
too. A declaration has one such comment: two adjacent ones would be read as
one, so they are reported.
Each binding carries the doc comment into the documentation format of its
language. It carries the brief, the paragraphs after the brief, @note,
@see and @deprecated, the @param text of each parameter that the
caller passes, and @return. A function documented with @errno behaves
differently in every binding except the C API: the binding returns the value
and reports a failure as an error. The @return text of such a function
describes both, and yace cannot separate the two. Each binding therefore shows
that text where it documents errors: under # Errors in Rust, Raises: in
Python, @throws in C++, and Errors: in Zig and Go. The text starts with
the name of the C function, as in foo_open() returns: 0 on success, ....
With @errno partial, a sentence follows that says where the error holds
what the call wrote: partial of the OSError in Python, value of
the Partial error in Rust and of the partial_error exception in C++,
the values returned with the error in Go, and the trailing partial
parameter in Zig, whose errors carry no value.