Back to the example

Going back to posix_system(), you should now be able to understand this bit:

        if (!getargs(args, "s", &command))
            return NULL;

It returns NULL (the error indicator for functions of this kind) if an error is detected in the argument list, relying on the exception set by getargs(). Otherwise the string value of the argument has been copied to the local variable command - this is in fact just a pointer assignment and you are not supposed to modify the string to which it points.

If a function is called with multiple arguments, the argument list (the argument args) is turned into a tuple. If it is called without arguments, args is NULL. getargs() knows about this; see later.

The next statement in posix_system() is a call to the C library function system(), passing it the string we just got from getargs():

        sts = system(command);

Finally, posix.system() must return a value: the integer status returned by the C library system() function. This is done using the function mkvalue(), which is something like the inverse of getargs(): it takes a format string and a variable number of C values and returns a new Python object.

        return mkvalue("i", sts);

In this case, it returns an integer object (yes, even integers are objects on the heap in Python!). More info on mkvalue() is given later.

If you had a function that returned no useful argument (a.k.a. a procedure), you would need this idiom:

        INCREF(None);
        return None;

None is a unique Python object representing `no value'. It differs from NULL, which means `error' in most contexts.