From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: AS22989 209.51.188.0/24 X-Spam-Status: No, score=-3.9 required=3.0 tests=AWL,BAYES_00, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,RCVD_IN_DNSWL_MED, RCVD_IN_MSPIKE_H2,SPF_HELO_PASS,SPF_PASS shortcircuit=no autolearn=ham autolearn_force=no version=3.4.6 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by dcvr.yhbt.net (Postfix) with ESMTPS id 702781F47C for ; Mon, 16 Jan 2023 13:44:15 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pHPmR-00048R-G6; Mon, 16 Jan 2023 08:44:07 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pHPmN-00047Y-0L for bug-gnulib@gnu.org; Mon, 16 Jan 2023 08:44:03 -0500 Received: from haproxy.adestotech.com ([217.163.77.122]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pHPmI-0004FS-WE for bug-gnulib@gnu.org; Mon, 16 Jan 2023 08:44:02 -0500 Received: from skynet19.adestotech.com (unknown [192.168.129.19]) by haproxy.adestotech.com (Postfix) with ESMTP id 18B92A1472; Mon, 16 Jan 2023 13:43:55 +0000 (GMT) From: Ondrej Valousek To: bug-gnulib@gnu.org Cc: Ondrej Valousek Subject: [PATCH] better explain functions [q]set-acl.c Date: Mon, 16 Jan 2023 14:42:45 +0100 Message-Id: <20230116134243.1701927-1-ondrej.valousek.xm@renesas.com> X-Mailer: git-send-email 2.39.0 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Received-SPF: pass client-ip=217.163.77.122; envelope-from=ondrej.valousek.xm@renesas.com; helo=haproxy.adestotech.com X-Spam_score_int: -8 X-Spam_score: -0.9 X-Spam_bar: / X-Spam_report: (-0.9 / 5.0 requ) AC_FROM_MANY_DOTS=1, BAYES_00=-1.9, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: bug-gnulib@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gnulib discussion list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnulib-bounces+normalperson=yhbt.net@gnu.org Sender: bug-gnulib-bounces+normalperson=yhbt.net@gnu.org Improve comments for both functions --- lib/qset-acl.c | 16 +++++++++------- lib/set-acl.c | 13 +++++++------ 2 files changed, 16 insertions(+), 13 deletions(-) diff --git a/lib/qset-acl.c b/lib/qset-acl.c index c3442d060f..0ae026f031 100644 --- a/lib/qset-acl.c +++ b/lib/qset-acl.c @@ -27,13 +27,15 @@ #include "acl-internal.h" -/* Set the access control lists of a file. If DESC is a valid file - descriptor, use file descriptor operations where available, else use - filename based operations on NAME. If access control lists are not - available, fchmod the target file to MODE. Also sets the - non-permission bits of the destination file (S_ISUID, S_ISGID, S_ISVTX) - to those from MODE if any are set. +/* Set the access control lists of a file to match *exactly* MODE (this might + remove inherited ACLs). Note chmod() tends to honor inherited/default + ACLs. If DESC is a valid file descriptor, use file descriptor operations + where available, else use filename based operations on NAME. If access + control lists are not available, fchmod the target file to MODE. Also + sets the non-permission bits of the destination file + (S_ISUID, S_ISGID, S_ISVTX) to those from MODE if any are set. Return 0 if successful. Return -1 and set errno upon failure. */ int qset_acl (char const *name, int desc, mode_t mode) diff --git a/lib/set-acl.c b/lib/set-acl.c index 9111911864..561ff47824 100644 --- a/lib/set-acl.c +++ b/lib/set-acl.c @@ -29,12 +29,13 @@ #define _(msgid) gettext (msgid) -/* Set the access control lists of a file. If DESC is a valid file - descriptor, use file descriptor operations where available, else use - filename based operations on NAME. If access control lists are not - available, fchmod the target file to MODE. Also sets the - non-permission bits of the destination file (S_ISUID, S_ISGID, S_ISVTX) - to those from MODE if any are set. +/* Set the access control lists of a file to match *exactly* MODE (this might + remove inherited ACLs). Note chmod() tends to honor inherited/default + ACLs. If DESC is a valid file descriptor, use file descriptor operations + where available, else use filename based operations on NAME. If access + control lists are not available, fchmod the target file to MODE. Also + sets the non-permission bits of the destination file + (S_ISUID, S_ISGID, S_ISVTX) to those from MODE if any are set. Return 0 if successful. On failure, output a diagnostic, set errno and return -1. */ -- 2.39.0