12

There are man(2) pages for the system calls, but these describe the behavior of the C library (glibc) that sits on top of the system calls. Is the raw system call API/ABI documented somewhere (other than UseTheSourceLuke)? I saw some mention of differences between kernel/libc in the man pages, but i did not get the feeling that it is a top priority to document these differences.

What i really mean to say is: Is the C library considered to be the stable/documented Linux API by POLICY, and the system call API/ABI of the kernel is considered unstable (may change) and therefore undocumented on purpose or low priority?

So kernel developers that change a system call make workarounds in glibc? What about the other libc's then?

Can i find historical discussions about this subject?

Edit: So the ABI is stable, and also the behavior of syscalls, but they are not documented by kernel developers. The glibc is documenting them instead (with its own additions/changes). Correct?

ctrl-d
  • 392
  • 1
  • 8
  • 1
    re: _historical discussion_. You might find something ***[here](https://www.safaribooksonline.com/library/view/linux-system-programming/9781449341527/ch01.html)***. No depth, but more of an overview of topics, including API/ABI. – ryyker Dec 10 '15 at 14:19
  • If your are asking about how system call arguments are passed to the kernel then the ABI is stable within a given processor architecture. Across processor architectures is where you will see variance in the ABI. – JJF Dec 10 '15 at 14:33
  • If the ABI is stable, and also the behavior of the system calls, there could be documentation for it, i guess. – ctrl-d Dec 10 '15 at 14:40
  • It's stable (for a particular architecture) in that changes are backwards compatible to avoid breaking old user-space code. – Ian Abbott Dec 10 '15 at 14:43
  • So a libc binary written 12 years ago would still work with a recent kernel? – ctrl-d Dec 10 '15 at 15:03
  • 1
    There is a good chance that a Linux libc written for the latest stable kernel of 12 years ago (i.e. one of the v2.6 line) would work with a modern kernel. You can in fact see that happen, sort of, with RHEL / CentOS 6, which is based on a 2.6-series kernel, but which you can switch easily to more recent kernels, e.g. by installing a kernel package from EL-repo. – John Bollinger Dec 10 '15 at 15:40

3 Answers3

3

I don't think the kernel developers actually post the interrupt API, but you can find third-party charts like this one.

owacoder
  • 4,815
  • 20
  • 47
  • 2
    Of course, if you do go for such a chart, then you should choose one that matches your kernel version. The one linked to is for Linux 2.2. It was therefore a bit dated in 2004 when it was posted, and now it is quite obsolete. – John Bollinger Dec 10 '15 at 14:39
  • 2
    @JohnBollinger - It is true it was for an older kernel version, but the author of the page also gives you the resources to create your own chart for a newer kernel. Also, though you say it is "quite obsolete," many of the calls have not changed up to the newest kernel. (I've tested several when implementing my own compiler.) – owacoder Dec 10 '15 at 15:03
  • @JohnBollinger: owacoder is correct. Linus has been very consistent about not breaking the user-space ABI. Instead of modifying existing system calls, they add a new version of the syscall with a new name. So you'll find stuff like [`mmap2(2)`](http://man7.org/linux/man-pages/man2/mmap2.2.html) for mapping big offsets into a large file on a 32bit system. Internally, the old syscall entry point usually becomes a wrapper that implements the old behaviour on top of the new function. So a new chart would have new versions of syscalls which are now preferred. – Peter Cordes Dec 10 '15 at 20:59
2

The answer to your question is in the syscall man page. Particularly pay attention to the section title "Architecture calling conventions" and note as mentioned by John Bollinger above that this information could vary among kernel versions.

JJF
  • 2,681
  • 2
  • 18
  • 31
0

What i really mean to say is: Is the C library considered to be the stable/documented Linux API by POLICY, and the system call API/ABI of the kernel is considered unstable (may change) and therefore undocumented on purpose or low priority?

It's impossible to speak to policy without specifying whose policy, for what.

People programming for "Linux" typically are in fact programming for one or more flavors of GNU / Linux, as opposed to for the bare kernel. I'm therefore inclined to say that we're probably not considering kernel developer policy. Indeed, if the C library interface is available at all then we're not talking about a bare kernel. Moreover, based on your tagging, I'm supposing you're asking about C programming. If you were programming in assembly then the raw syscall interface would be natural and appropriate, and most of the rest of my comments would not apply.

If you are indeed targeting GNU / Linux to the exclusion of anything else, then the question is somewhat sensible. On the other hand, it is often the case that one would prefer to program for broader compatibility. In that case, there really is no alternative to using the C-library syscall interfaces, because each system's raw syscalls are different. Glibc's syscall interfaces do a pretty good job of conforming with POSIX and SUS, so using them (properly) is a tremendous advantage for portability. Even if other Unix and Unix-like systems, such as OS X, BSD, Solaris, etc. are not immediate targets, it is rarely a loss to hold open the possibility of using your software on such systems.

Anyway, if you were determined to have your software execute Linux syscalls directly, then would you indeed insert inline assembly to do that everywhere you wanted it? Surely not -- you would write wrapper functions. Why, then, should you object to using the thoroughly tested and well-documented wrapper functions already provided by the C library?

Certainly the Linux syscall interface does change to some extent between kernel versions. That can be considered the thing that makes versions different (I mean x.2y -> x.2z or x.y -> z.w). I'm not well tuned in to how large such changes typically are, but there have been incompatible changes in the past, and using the C library interfaces insulates you from such changes to some extent. As described above, however, I think there are other, larger reasons for preferring the C library interface.

John Bollinger
  • 160,171
  • 8
  • 81
  • 157
  • With the policy i really meant that of the kernel developers. And if i wanted to write an embedded platform with only the bare linux kernel in it, where do i get documentation in that case? Is it undocumented in that scenario? – ctrl-d Dec 10 '15 at 15:38
  • 1
    @ctrl-d, then for goodness sake, why didn't you say so? The C library interface is moot if you don't have the C library to draw on. Do, please, revise your question to ask what you really want to know. – John Bollinger Dec 10 '15 at 15:45
  • Sorry if i caused confusion, really. It's a theoretical question about policy, not practice per-se. How should i have asked the question otherwise? – ctrl-d Dec 10 '15 at 15:50
  • @ctrl-d, if you are hypothesizing direct syscalls then any mention of the C library other than to disclaim its usage is a red herring, and should have been avoided. The question you seem really to have wanted to ask is something like "where can I find documentation of Linux's raw syscalls?", perhaps augmented with "How stable are they?". The former is *not*, in fact, a policy question, although the latter does touch on kernel development policy. – John Bollinger Dec 10 '15 at 15:58
  • 2
    Maybe i should have kept it to the title alone then. But i kindly disagree with you that it's not a policy thing to make documentation or not for the raw kernel by developers. – ctrl-d Dec 10 '15 at 16:21
  • " Why, then, should you object to using the thoroughly tested and well-documented wrapper functions already provided by the C library?" Because they use `errno` for reporting errors, instead of just returning the error code directly like the raw syscalls... – gnzlbg Sep 08 '19 at 16:16