From patchwork Sat Dec 3 20:22:36 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Alejandro Colomar X-Patchwork-Id: 55339 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id E69D3385B50B for ; Sat, 3 Dec 2022 20:23:44 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org E69D3385B50B DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1670099024; bh=ivgq95ghXHilfYx7N6xlLPnCx53obJv2fsof4Ef0rkw=; h=To:Cc:Subject:Date:List-Id:List-Unsubscribe:List-Archive: List-Post:List-Help:List-Subscribe:From:Reply-To:From; b=eEJGLnYWU7j7Uliu3SDUekemwsxKvKoFjjO7RKjRc7HG1cfSDo1XosKscXVm5+iUq AfmE+u4kATyXhGiaAX1g0UfEfUp9B5D+sRDHcCnEQ1eHg2j2hZrVRBu3wgpEvUfTpL VgQXdcnvqlj4kJNGWYXDf87NFcqjn4DKEANHsBzk= X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from mail-wr1-x430.google.com (mail-wr1-x430.google.com [IPv6:2a00:1450:4864:20::430]) by sourceware.org (Postfix) with ESMTPS id 751EF3858D20 for ; Sat, 3 Dec 2022 20:23:21 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 751EF3858D20 Received: by mail-wr1-x430.google.com with SMTP id h12so12903885wrv.10 for ; Sat, 03 Dec 2022 12:23:21 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=ivgq95ghXHilfYx7N6xlLPnCx53obJv2fsof4Ef0rkw=; b=nJOFGiaf2yErwvrVjI2e9A7/WKxKB3NaT8p7N7kHk0GviHiiGLaTMgfz8DnN3fdFEB 7lDH+cTphDxy/6iHFU3JgSbTEli9qu+fZPsJoCSzEkQ8xkNxaI68ZTeK32SYdHkZ82UZ RAL3RG+VYlPWF3RrbgewABHQJu0uYxLQvFZYDhvqE4CzMfFgST0IBAZTqtSWQvrKZ9WG wCrkYBwGdBc0HGKLpsE99e2HhBD5rOo0w+uvbX2FZt1Rzjqb1S795iLUzdarDnKlRicP 97mQVNvaPd2G4nyLN3wahOh8ZNFOXz6zm4ItVMwnv/zjLBJDXAEw5p/Q1BbAOGc96U8C 8mgg== X-Gm-Message-State: ANoB5pl2LLR3oCVME4Dnf4JWyHhsu2FBMcZukc00wO/2rZs1xm7LOGLk 4SoZOW8VzLvfSjNlbxbDAJFEn1vmCHM= X-Google-Smtp-Source: AA0mqf6PvQ4fOdkHFl+Csgw266QdH7t4kRleEdJRdXouWZ7YkvN6IUX6AZsnbtDF8zxuWuMoeu1eng== X-Received: by 2002:a5d:5045:0:b0:242:199a:e067 with SMTP id h5-20020a5d5045000000b00242199ae067mr17233637wrt.148.1670099000028; Sat, 03 Dec 2022 12:23:20 -0800 (PST) Received: from asus5775.alejandro-colomar.es ([170.253.36.171]) by smtp.googlemail.com with ESMTPSA id p17-20020a5d68d1000000b002420cfcd13dsm10064481wrw.105.2022.12.03.12.23.19 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 03 Dec 2022 12:23:19 -0800 (PST) X-Google-Original-From: Alejandro Colomar To: linux-man@vger.kernel.org Cc: Alejandro Colomar , 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> X-Mailer: git-send-email 2.38.1 MIME-Version: 1.0 X-Spam-Status: No, score=-4.8 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_FROM, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Alejandro Colomar via Libc-alpha From: Alejandro Colomar Reply-To: Alejandro Colomar Errors-To: libc-alpha-bounces+patchwork=sourceware.org@sourceware.org Sender: "Libc-alpha" 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(-)