Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
From:   Alejandro Colomar <alx.manpages@gmail.com>
To:     linux-man@vger.kernel.org
Cc:     Alejandro Colomar <alx@kernel.org>, libc-alpha@sourceware.org,
        linux-kernel@vger.kernel.org
Subject: [PATCH 00/41] Document nullability of syscall parameters
Date:   Sat,  3 Dec 2022 21:22:36 +0100
Message-Id: <20221203202317.252789-1-alx@kernel.org>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk


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