[PATCH 00/41] Document nullability of syscall parameters

Alejandro Colomar
2022-12-03T20:23:24Z

Hi!

This patch set documents which parameters of syscalls accept NULL.
Actually, some syscalls may also accept it (but return always an error),
but per the recent discussion on the glibc mailing list, I decided to
ignore that behavior and treat them as if they were _Nonnull.

So when a function is documented with a _Nullable parameter, it means
that calling the function with NULL is meaningful.

I decided to use one of the Clang qualifiers because the
[[gnu::nonnull]] attribute is not as precise (for example in the case of
pointers to pointers).

I decided to use _Nullable and not _Nonnull because there are many more
functions that don't accept NULL than those that do, so _Nullable is the
least noisy.

When POSIX or other systems are more restrictive than GNU/Linux, I chose
to be more restrictive in the prototype, to avoid confusion (this is
similar to what was done with 'restrict', which was specified if any
system or POSIX used it, even if glibc didn't require restrict --maybe
those were glibc bugs--).

Cheers,

Alex

Alejandro Colomar (41):
accept.2: SYNOPSIS: Add _Nullable
acct.2: SYNOPSIS: Add _Nullable
clock_getres.2: SYNOPSIS: Add _Nullable
clock_nanosleep.2: SYNOPSIS: Add _Nullable
clone.2: SYNOPSIS: Add _Nullable
copy_file_range.2: SYNOPSIS: Add _Nullable
epoll_ctl.2: SYNOPSIS: Add _Nullable
epoll_wait.2: SYNOPSIS: Add _Nullable
execve.2: SYNOPSIS: Add _Nullable
execveat.2: SYNOPSIS: Add _Nullable
fanotify_mark.2: SYNOPSIS: Add _Nullable
getcpu.2: SYNOPSIS: Add _Nullable
getgroups.2: SYNOPSIS: Add _Nullable
getitimer.2: SYNOPSIS: Add _Nullable
getrlimit.2: SYNOPSIS: Add _Nullable
gettimeofday.2: SYNOPSIS: Add _Nullable
listxattr.2: SYNOPSIS: Add _Nullable
mount.2: SYNOPSIS: Add _Nullable
nanosleep.2: SYNOPSIS: Add _Nullable
pidfd_send_signal.2: SYNOPSIS: Add _Nullable
poll.2: SYNOPSIS: Add _Nullable
quotactl.2: SYNOPSIS: Add _Nullable
recv.2: SYNOPSIS: Add _Nullable
request_key.2: SYNOPSIS: Add _Nullable
select.2: SYNOPSIS: Add _Nullable
semop.2: SYNOPSIS: Add _Nullable
sendfile.2: SYNOPSIS: Add _Nullable
shmop.2: SYNOPSIS: Add _Nullable
sigaction.2: SYNOPSIS: Add _Nullable
sigaltstack.2: SYNOPSIS: Add _Nullable
sigprocmask.2: SYNOPSIS: Add _Nullable
sigwaitinfo.2: SYNOPSIS: Add _Nullable
splice.2: SYNOPSIS: Add _Nullable
time.2: SYNOPSIS: Add _Nullable
timer_create.2: SYNOPSIS: Add _Nullable
timer_settime.2: SYNOPSIS: Add _Nullable
timerfd_create.2: SYNOPSIS: Add _Nullable
utime.2: SYNOPSIS: Add _Nullable
utimensat.2: SYNOPSIS: Add _Nullable
wait.2: SYNOPSIS: Add _Nullable
wait4.2: SYNOPSIS: Add _Nullable

man2/accept.2 | 8 ++++----
man2/acct.2 | 2 +-
man2/clock_getres.2 | 2 +-
man2/clock_nanosleep.2 | 2 +-
man2/clone.2 | 10 ++++++----
man2/copy_file_range.2 | 4 ++--
man2/epoll_ctl.2 | 2 +-
man2/epoll_wait.2 | 7 ++++---
man2/execve.2 | 4 ++--
man2/execveat.2 | 3 ++-
man2/fanotify_mark.2 | 4 ++--
man2/getcpu.2 | 3 ++-
man2/getgroups.2 | 2 +-
man2/getitimer.2 | 2 +-
man2/getrlimit.2 | 5 +++--
man2/gettimeofday.2 | 4 ++--
man2/listxattr.2 | 6 +++---
man2/mount.2 | 2 +-
man2/nanosleep.2 | 3 ++-
man2/pidfd_send_signal.2 | 5 ++---
man2/poll.2 | 3 ++-
man2/quotactl.2 | 4 ++--
man2/recv.2 | 4 ++--
man2/request_key.2 | 2 +-
man2/select.2 | 16 +++++++++-------
man2/semop.2 | 2 +-
man2/sendfile.2 | 5 +++--
man2/shmop.2 | 3 ++-
man2/sigaction.2 | 5 +++--
man2/sigaltstack.2 | 4 ++--
man2/sigprocmask.2 | 15 ++++++++-------
man2/sigwaitinfo.2 | 4 ++--
man2/splice.2 | 6 +++---
man2/time.2 | 2 +-
man2/timer_create.2 | 3 ++-
man2/timer_settime.2 | 2 +-
man2/timerfd_create.2 | 2 +-
man2/utime.2 | 6 ++++--
man2/utimensat.2 | 4 ++--
man2/wait.2 | 4 ++--
man2/wait4.2 | 7 ++++---
41 files changed, 100 insertions(+), 83 deletions(-)

--
2.38.1