Re: New system calls, fsopen()/fsconfig()/fsmount() and friends

[Florian Weimer <fweimer at redhat dot com>]

* Ian Kent:

> I see the names for the new system calls fsopen()/fsconfig()/fsmount()
> and friends have been added to the syscall names list in the repo.
>
> I'm wondering what the process is for adding them to glibc.
>
> I would like to help out with what needs to be done to properly
> add them to glibc but I'm not familiar with the processes involved.

First, we need to make sure that you are covered by some copyright
assignment.  (I think we have already established that.)

For functions which do not need new types, the process is roughly like
this:

* Add the function prototype to one of the installed headers,
  perhaps protected by __USE_GNU if it is a standard header.
* Add the function name to sysdeps/unix/sysv/linux/Versions, under
  the libc entry for the upcoming glibc version.
* Add the system call to sysdeps/unix/sysv/linux/syscalls.list.
* Write a basic test, in a sysdeps/unix/sysv/linux/tst-*.c file.
* Add it to tests in the appropriate $(subdir) conditional in
  sysdeps/unix/sysv/linux/Makefile (the choice is somewhat arbitrary,
  and it can be misc).
* Add documentation to the manual for the new function.
* Add a NEWS entry.
* Update the abi lists after make && make check, using
  make update-all-abi.

This commit is pretty minimal:

commit 04b261bdc13afd1f7644c756a23df3d43d400fa4
Author: Florian Weimer <fweimer@redhat.com>
Date:   Tue May 14 21:35:09 2019 +0200

    Linux: Add the tgkill function
    
    The tgkill function is sometimes used in crash handlers.
    
    <bits/signal_ext.h> follows the same approach as <bits/unistd_ext.h>
    (which was added for the gettid system call wrapper).
    
    Reviewed-by: Carlos O'Donell <carlos@redhat.com>

The only non-standard part is the addition of <bits/signal_ext.h>, so
that we can easily add Linux-specific functionality to <sys/signal.h>.

> Things like, where should the constant defines end up, and how do
> they get there from the kernel headers, how are they kept up to
> date, etc. ?

If you need types, then we probably want a copy of the definitions in
the glibc headers and use __has_include.  See
sysdeps/unix/sysv/linux/bits/statx.h for an example.  This only works if
the UAPI headers are clean and do not have too many dependencies on
problematic UAPI headers.

In this case, you should add a new installed header.  It should be
stored in sysdeps/unix/sysv/linux/sys (so that it's included as
<sys/…>), and added to sysdep_headers in the appropriate $(subdir)
conditional in sysdeps/unix/sysv/linux/Versions.

If the new API is designed for GNU, some of the changes should not be
Linux-specific.  In particular, an installed header not under sysdeps/
needs a wrapper header in include/.

> And what are the conventions used when writing functions that wrap
> these calls, and anything else I should know to do this?

A lot of the wrappers can be auto-generated from syscalls.list entries.
That is the preferred approach.  If that is not possible, there aren't
any general rules because it's just general software development.

Thanks,
Florian