Where are the OSX (XNU) syscalls actually documented?

Question

I'm looking through the syscalls.master file here but it isn't at all documented. Does documentation for the syscalls exist? If not, why not?

By documentation I mean an actual explanation of what each syscall does and the meanings of the arguments it takes.

Aalto

from the OS/X command line you should be able to do man 2 functionname where functionname is the system call function.You can also look up the functions here: freebsd.org/cgi/man.cgi – Gilcrest

In addition to the assembly tag please indicate which instruction set. – Penta

@Penta doesn't XNU use a single instruction set? I tagged this with XNU – Aalto

@ubadub: according to en.wikipedia.org/wiki/XNU#Kernel_design, it used to run on PowerPC, and in 2007 runs on ARM and x86. (And on x86, both IA-32 and x86-64). I tagged it for you based on your comment. – Neuromuscular

@PeterCordes thanks! – Aalto

I didnt see an architecture related to XNU in the XNU SO description, but I did see in the assembly tag in capital letters, to also tag the instruction set. – Penta

Answer 1

Apple's position is that the system libraries are the API and stable ABI, syscalls are not. They discourage their direct use, as they can change from release to release of the OS.

So, the best documentation you'll see is the man pages in section 2 or, in some cases, the headers in /usr/include. Of course, you can also look at the XNU sources for the implementations of the syscalls to see how they work.

Note that many of the system calls in syscalls.master are for internal use only and have no documentation. Also, syscalls.master contains only the Unix syscalls, not, for example, the Mach syscalls.

Julijulia

how do you call the API/stable API from assembly (x86-64)? – Aalto

@ubadub: I'd assume it's like any other Unix system: link with libc and call the system call wrapper functions in it. e.g. mov edi,1 / lea rsi, [rel msg] / mov edx, msglen / call write to invoke the POSIX write system call (man7.org/linux/man-pages/man3/write.3p.html) with the x86-64 System V calling convention. – Neuromuscular

Yes, more or less. The same way you call any external function. You'd prefix the function name with an underscore, though (e.g. _write). A useful technique is to write a C file that does what you're interested in, compile it to assembly (e.g. cc -S -o foo.s foo.c), and then read that assembly to see how it did it. Also, on macOS, the C library is in libSystem, although libc is an alias for it. – Julijulia