3 ms·

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 alw

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?

andrewmcwatters 9mo ago
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.
- hugmynutus 9mo ago
  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.
surajrmal 9mo ago
Fun fact, those numbers are also not consistent per architecture. Any similarly named syscalls can have very different abi on different architectures.
- yjftsjthsd-h 9mo ago
  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.
dundarious 9mo ago
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).
- adrian_b 9mo ago
  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.
  - dundarious 9mo ago
    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.
t-3 9mo ago
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.
- dundarious 9mo ago
  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.
  - t-3 9mo ago
    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.
    - adrian_b 9mo ago
      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.
      - t-3 9mo ago
        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.
  - 9mo ago

andrewmcwatters 9mo ago

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.

hugmynutus 9mo ago
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.

surajrmal 9mo ago

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

yjftsjthsd-h 9mo ago
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.

dundarious 9mo ago

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).

adrian_b 9mo ago
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.
- dundarious 9mo ago
  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.

t-3 9mo ago

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.

dundarious 9mo ago
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.
- t-3 9mo ago
  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.
  - adrian_b 9mo ago
    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.
    - t-3 9mo ago
      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.
- 9mo ago