4

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.

Peter Cordes
  • 328,167
  • 45
  • 605
  • 847
ubadub
  • 3,571
  • 21
  • 32
  • 1
    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: https://www.freebsd.org/cgi/man.cgi – Michael Petch Nov 01 '18 at 18:50
  • In addition to the assembly tag please indicate which instruction set. – old_timer Nov 01 '18 at 18:53
  • @old_timer doesn't XNU use a single instruction set? I tagged this with XNU – ubadub Nov 01 '18 at 22:03
  • 1
    @ubadub: according to https://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. – Peter Cordes Nov 01 '18 at 22:14
  • @PeterCordes thanks! – ubadub Nov 01 '18 at 22:21
  • 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. – old_timer Nov 02 '18 at 02:50

1 Answers1

8

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.

Ken Thomases
  • 88,520
  • 7
  • 116
  • 154
  • how do you call the API/stable API from assembly (x86-64)? – ubadub Nov 01 '18 at 22:10
  • 2
    @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 (http://man7.org/linux/man-pages/man3/write.3p.html) with the x86-64 System V calling convention. – Peter Cordes Nov 01 '18 at 22:17
  • 3
    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. – Ken Thomases Nov 01 '18 at 22:21