From: Alejandro Colomar via Libc-alpha <libc-alpha@sourceware.org>
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 [thread overview]
Message-ID: <20221203202317.252789-1-alx@kernel.org> (raw)
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
next reply other threads:[~2022-12-03 20:23 UTC|newest]
Thread overview: 42+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-12-03 20:22 Alejandro Colomar via Libc-alpha [this message]
2022-12-03 20:22 ` [PATCH 01/41] accept.2: SYNOPSIS: Add _Nullable Alejandro Colomar via Libc-alpha
2022-12-03 20:22 ` [PATCH 02/41] acct.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:22 ` [PATCH 03/41] clock_getres.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:22 ` [PATCH 04/41] clock_nanosleep.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:22 ` [PATCH 05/41] clone.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:22 ` [PATCH 06/41] copy_file_range.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:22 ` [PATCH 07/41] epoll_ctl.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:22 ` [PATCH 08/41] epoll_wait.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:22 ` [PATCH 09/41] execve.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:22 ` [PATCH 10/41] execveat.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:22 ` [PATCH 11/41] fanotify_mark.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:22 ` [PATCH 12/41] getcpu.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:22 ` [PATCH 13/41] getgroups.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:22 ` [PATCH 14/41] getitimer.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:22 ` [PATCH 15/41] getrlimit.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:22 ` [PATCH 16/41] gettimeofday.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:22 ` [PATCH 17/41] listxattr.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:22 ` [PATCH 18/41] mount.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:22 ` [PATCH 19/41] nanosleep.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:22 ` [PATCH 20/41] pidfd_send_signal.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:22 ` [PATCH 21/41] poll.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:22 ` [PATCH 22/41] quotactl.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:22 ` [PATCH 23/41] recv.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:23 ` [PATCH 24/41] request_key.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:23 ` [PATCH 25/41] select.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:23 ` [PATCH 26/41] semop.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:23 ` [PATCH 27/41] sendfile.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:23 ` [PATCH 28/41] shmop.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:23 ` [PATCH 29/41] sigaction.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:23 ` [PATCH 30/41] sigaltstack.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:23 ` [PATCH 31/41] sigprocmask.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:23 ` [PATCH 32/41] sigwaitinfo.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:23 ` [PATCH 33/41] splice.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:23 ` [PATCH 34/41] time.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:23 ` [PATCH 35/41] timer_create.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:23 ` [PATCH 36/41] timer_settime.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:23 ` [PATCH 37/41] timerfd_create.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:23 ` [PATCH 38/41] utime.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:23 ` [PATCH 39/41] utimensat.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:23 ` [PATCH 40/41] wait.2: " Alejandro Colomar via Libc-alpha
2022-12-03 20:23 ` [PATCH 41/41] wait4.2: " Alejandro Colomar via Libc-alpha
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/libc/involved.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20221203202317.252789-1-alx@kernel.org \
--to=libc-alpha@sourceware.org \
--cc=alx.manpages@gmail.com \
--cc=alx@kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-man@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).