Hacker News Reader

Comment by yjftsjthsd-h | Hacker News Reader

I remain surprised that people have to make unofficial syscall lists at all. Linux takes the view that syscalls are the official stable ABI of the kernel. I always assumed, therefore, that if that was the official interface, then it would of course be a documented interface. That assumption lasted right up until recently when I decided to learn assembly, and discovered that no, if I wanted to know what numbers to shove in registers before running syscall, I have to look up unofficial tables/docs. Like... that's weird, right? If this was another OS, they'd say that libc was the official interface so of course syscalls are an undocumented implementation detail. But when syscalls are the official interface, for them to be undocumented seems bizarre. Am I missing something?

View on HN

There's nothing strange in this domain about relying on people to read the C header. On a running system `man syscall` points you to sys/syscall.h. Read /usr/include/sys/syscall.h which says it gets the actual numbers from kernel header asm/unistd.h. Read that and it redirects in simple if-else fashion to the specific header, e.g., asm/unistd_64.h. That file is clear as day:

    #ifndef _ASM_UNISTD_64_H
    #define _ASM_UNISTD_64_H

    #define __NR_read 0
    #define __NR_write 1
    #define __NR_open 2
    ...
    #endif /* _ASM_UNISTD_64_H */

That was all on my x86-64 machine. Same again on an aarch64:

    #define __NR_io_setup 0                                                                                                               
    #define __NR_io_destroy 1                                                                                                             
    #define __NR_io_submit 2 
    ...

I'm not saying that wanting a table on the web or a spreadsheet or whatever is bad or wrong, but it is not a difficult or obtuse task. I think people who write code that does such things are generally familiar with just reading some C headers, or if they're already using C they just `#include <sys/syscall.h>` and call it a day.

Then on the calling convention, etc., the nolibc project (in the kernel tree) is great for learning or smaller projects (but of course Agner Fog's docs are the "canon" there).

The header mentioned by you does not belong to Linux.

It is a glibc header. It is the right header to use when you invoke syscalls using the generic syscall wrappers provided by glibc.

However, glibc frequently is not synchronized with your current Linux kernel, but with some older version, so this header typically does not contain the most recently added syscalls. Even for the older syscalls, I am not certain that glibc provides all of them.

The authoritative list of syscalls must be gathered from the Linux kernel headers, not from glibc. What must be done for this is not as simple as you would expect, hence the several places mentioned by various posters where this tedious work has been done.

True, I've had to deal with that for newer syscalls and the few that glibc neglects to cover. I didn't mention it, and I suppose the original post was about lack of kernel documentation, so mentioning a glibc source (or musl or whatever) is misleading in a way I didn't originally consider.

It is somewhat documented. man 2 syscalls tells me they are defined in /usr/include/asm/unistd.h. That file include /usr/include/asm/unistd_{32,64}.h, which contain the definitions on my amd64 linux box. On my aarch64 they're in /usr/include/asm-generic/unistd.h, but the syscalls manfile doesn't mention the changed path.

The manpage defines the interface in terms of sys/syscall.h where it leads to the right place on every platform I've ever worked on, and which is where I would first look, but yeah, maybe not all sections are clear.

That's the syscall(9) manpage, not the syscalls(2) manpage. syscall(9) is present on BSD as well, and on my OpenBSD box points me to sys/syscall.h which has the syscalls. On linux sys/syscall.h is empty and includes asm/unistd.h.

The manpage syscall(2) exists on both Linux and FreeBSD, while syscall(9) does not exist on either of them.

On Linux there is also a syscalls(2) manpage, while no syscalls page exists on FreeBSD.

These man pages belong to libc (e.g. glibc on Linux), not to the kernel. This distinction does not matter on FreeBSD and other *BSD, where the kernel and the standard C library are always synchronized, but it matters on Linux, where glibc and the kernel are developed independently, so their lists of syscalls are not the same. Typically glibc is synchronized with an older Linux kernel, not with your current kernel.

Ah, you're right. syscall(2) must have been moved to syscall(9) on OpenBSD when the syscall function was removed and pinsyscalls was added.

That syscall man page is from glibc and provides information about how you can invoke syscalls through glibc.

It does not have any direct connection with the Linux kernel. Because the Linux kernel promises that the syscall interface is stable, in the normal situation when the kernel is newer or at least of the same age with glibc, all the syscalls that can be invoked through glibc should be supported by the kernel, but the kernel may support extra syscalls.

If you install a kernel that is older than glibc, which may happen in some embedded systems that are compatible only with some old kernels, then it may be that the kernel does not support all the syscalls from the glibc headers.

Those are glibc headers not Linux kernel headers.

The glibc headers do not necessarily match your current Linux kernel.

You should use the glibc headers when you use the glibc generic syscall wrappers, but otherwise you must not consider them as an authoritative source for syscalls, because they frequently do not contain all the syscalls provided by your current kernel.

> Those are glibc headers not Linux kernel headers.

You're right in principle: but more precisely, they are the kernel headers for the kernel version which the system glibc was built against. But they are actually from the kernel source, not the glibc source.

Fun fact, those numbers are also not consistent per architecture. Any similarly named syscalls can have very different abi on different architectures.

IIRC, there are also differences in what syscalls even exist per-arch... although I suppose technically that doesn't have to preclude their numbers lining up.

For that matter, how you even make syscalls varies by arch, eg.

  syscall

on x86_64 vs

  int 0x80

on i386.

All people unfamiliar with Linux at a documentation level assume that because Linux is Linux it must be pretty well documented, but in reality, just building the thing and creating an init is extremely poorly documented process for such mature software.

You’re not missing anything. It’s amazing Linux makes any progress at all, because the most high touch points about the damn thing are basically completely undocumented.

And if they are, the documentation is out of date, and written by some random maintainer and describes a process no longer used or it’s by a third-party and obviously wrong or superfluous and they have no idea what they’re talking about.

Edit: Oh it’s a cultural issue, too. Almost everything revolving around Linux documentation is also an amateur shitshow. Systemd, that init system and so much more that everyone uses? How do you build it and integrate it into a new image?

I don’t know. They don’t either. It’s assumed you’re already using it from a major distribution. There’s no documentation for it.

docs.kernel.org is generated from in tree readmes, docs, type/struct/function definitions. Making it a lot easier to read/browse documentation that would (previously) require grepping the source code to find.

I realize the site also hosts some fairly out-of-date articles, there is room for improvement. Those hand written articles start with an author & timestamp, so they're easy to filter.

Reply on news.ycombinator.com