In most Gnulib modules, when we have a function that does something
and another function that does the same thing with diagnostics, the
common convention is that the latter has an 'x' prefix. Such as for
malloc — xalloc
vasprintf — xvasprintf
getcwd — xgetcwd
striconv — xstriconv
etc.
The modules 'acl' and 'copy-file' use an opposite convention:
qcopy_acl — copy_acl
This is so for historical reasons: the function which emits diagnostics
was there before the silent function.
In the name of consistency of the API, I'd like to migrate 'acl' and 'copy-file'
to the common conventions: In a first step
qcopy_acl — xcopy_acl
and then later (in a year or two):
copy_acl — xcopy_acl
At some point, we can then also rename the modules accordingly.
These two patches implement the first step: introducing the function with
'x' prefix.
2024-08-24 Bruno Haible <br...@clisp.org>
copy-file: First step towards more consistent function names.
* lib/copy-file.h (xcopy_file_preserving): New declaration.
(copy_file_preserving): Mark deprecated.
* lib/copy-file.c (xcopy_file_preserving): Renamed from
copy_file_preserving.
(copy_file_preserving): New function.
* tests/test-copy-file.c (main): Test xcopy_file_preserving instead of
copy_file_preserving.
acl: First step towards more consistent function names.
* lib/acl.h (xset_acl): New declaration.
(set_acl): Mark deprecated.
(xcopy_acl): New declaration.
(copy_acl): Mark deprecated.
* lib/set-acl.c (xset_acl): Renamed from set_acl.
(set_acl): New function.
* lib/copy-acl.c (xcopy_acl): Renamed from copy_acl.
(copy_acl): New function.
* tests/test-set-mode-acl.c (main): Test xset_acl instead of set_acl.
* tests/test-copy-acl.c (main): Test xcopy_acl instead of copy_acl.
From 8a71833114c376212ecdd56495604905f6aa218d Mon Sep 17 00:00:00 2001
From: Bruno Haible <br...@clisp.org>
Date: Sat, 24 Aug 2024 17:58:48 +0200
Subject: [PATCH 1/2] acl: First step towards more consistent function names.
* lib/acl.h (xset_acl): New declaration.
(set_acl): Mark deprecated.
(xcopy_acl): New declaration.
(copy_acl): Mark deprecated.
* lib/set-acl.c (xset_acl): Renamed from set_acl.
(set_acl): New function.
* lib/copy-acl.c (xcopy_acl): Renamed from copy_acl.
(copy_acl): New function.
* tests/test-set-mode-acl.c (main): Test xset_acl instead of set_acl.
* tests/test-copy-acl.c (main): Test xcopy_acl instead of copy_acl.
---
ChangeLog | 14 ++++++++++++++
lib/acl.h | 14 +++++++++++---
lib/copy-acl.c | 11 +++++++++--
lib/set-acl.c | 8 +++++++-
tests/test-copy-acl.c | 2 +-
tests/test-set-mode-acl.c | 2 +-
6 files changed, 43 insertions(+), 8 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 29c02f5478..b223243229 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+2024-08-24 Bruno Haible <br...@clisp.org>
+
+ acl: First step towards more consistent function names.
+ * lib/acl.h (xset_acl): New declaration.
+ (set_acl): Mark deprecated.
+ (xcopy_acl): New declaration.
+ (copy_acl): Mark deprecated.
+ * lib/set-acl.c (xset_acl): Renamed from set_acl.
+ (set_acl): New function.
+ * lib/copy-acl.c (xcopy_acl): Renamed from copy_acl.
+ (copy_acl): New function.
+ * tests/test-set-mode-acl.c (main): Test xset_acl instead of set_acl.
+ * tests/test-copy-acl.c (main): Test xcopy_acl instead of copy_acl.
+
2024-08-24 Paul Eggert <egg...@cs.ucla.edu>
diffseq: port to clang 18.1.6 in ‘patch’
diff --git a/lib/acl.h b/lib/acl.h
index 0bf78a654d..475231c2db 100644
--- a/lib/acl.h
+++ b/lib/acl.h
@@ -20,7 +20,7 @@
#ifndef _GL_ACL_H
#define _GL_ACL_H 1
-/* This file uses _GL_ATTRIBUTE_CONST. */
+/* This file uses _GL_ATTRIBUTE_CONST, _GL_ATTRIBUTE_DEPRECATED. */
#if !_GL_CONFIG_H_INCLUDED
#error "Please include config.h first."
#endif
@@ -35,10 +35,18 @@ extern "C" {
bool acl_errno_valid (int) _GL_ATTRIBUTE_CONST;
int file_has_acl (char const *, struct stat const *);
+
int qset_acl (char const *, int, mode_t);
-int set_acl (char const *, int, mode_t);
+int xset_acl (char const *, int, mode_t);
+/* Old name of xset_acl. */
+_GL_ATTRIBUTE_DEPRECATED int set_acl (char const *, int, mode_t);
+
int qcopy_acl (char const *, int, char const *, int, mode_t);
-int copy_acl (char const *, int, char const *, int, mode_t);
+int xcopy_acl (char const *, int, char const *, int, mode_t);
+/* Old name of xcopy_acl. */
+_GL_ATTRIBUTE_DEPRECATED int copy_acl (char const *, int, char const *, int,
+ mode_t);
+
int chmod_or_fchmod (char const *, int, mode_t);
diff --git a/lib/copy-acl.c b/lib/copy-acl.c
index bde98f0b26..b4aa920ed5 100644
--- a/lib/copy-acl.c
+++ b/lib/copy-acl.c
@@ -40,8 +40,8 @@
negative error code. */
int
-copy_acl (const char *src_name, int source_desc, const char *dst_name,
- int dest_desc, mode_t mode)
+xcopy_acl (const char *src_name, int source_desc, const char *dst_name,
+ int dest_desc, mode_t mode)
{
int ret = qcopy_acl (src_name, source_desc, dst_name, dest_desc, mode);
switch (ret)
@@ -59,3 +59,10 @@ copy_acl (const char *src_name, int source_desc, const char *dst_name,
}
return ret;
}
+
+int
+copy_acl (const char *src_name, int source_desc, const char *dst_name,
+ int dest_desc, mode_t mode)
+{
+ return xcopy_acl (src_name, source_desc, dst_name, dest_desc, mode);
+}
diff --git a/lib/set-acl.c b/lib/set-acl.c
index dd3b596805..08ce8b80db 100644
--- a/lib/set-acl.c
+++ b/lib/set-acl.c
@@ -39,10 +39,16 @@
return -1. */
int
-set_acl (char const *name, int desc, mode_t mode)
+xset_acl (char const *name, int desc, mode_t mode)
{
int ret = qset_acl (name, desc, mode);
if (ret != 0)
error (0, errno, _("setting permissions for %s"), quote (name));
return ret;
}
+
+int
+set_acl (char const *name, int desc, mode_t mode)
+{
+ return xset_acl (name, desc, mode);
+}
diff --git a/tests/test-copy-acl.c b/tests/test-copy-acl.c
index 4ca9210890..9970ea4ce1 100644
--- a/tests/test-copy-acl.c
+++ b/tests/test-copy-acl.c
@@ -60,7 +60,7 @@ main (int argc, char *argv[])
}
#if USE_ACL
- if (copy_acl (file1, fd1, file2, fd2, mode))
+ if (xcopy_acl (file1, fd1, file2, fd2, mode))
exit (EXIT_FAILURE);
#else
chmod (file2, mode);
diff --git a/tests/test-set-mode-acl.c b/tests/test-set-mode-acl.c
index 1c2217df57..8dcde9254f 100644
--- a/tests/test-set-mode-acl.c
+++ b/tests/test-set-mode-acl.c
@@ -35,7 +35,7 @@ main (int argc, char *argv[])
file = argv[1];
mode = strtol (argv[2], NULL, 8);
- set_acl (file, -1, mode);
+ xset_acl (file, -1, mode);
return test_exit_status;
}
--
2.34.1
>From e9655b05dc0b25d24457f9b8dd31a579d6867d83 Mon Sep 17 00:00:00 2001
From: Bruno Haible <br...@clisp.org>
Date: Sat, 24 Aug 2024 17:59:26 +0200
Subject: [PATCH 2/2] copy-file: First step towards more consistent function
names.
* lib/copy-file.h (xcopy_file_preserving): New declaration.
(copy_file_preserving): Mark deprecated.
* lib/copy-file.c (xcopy_file_preserving): Renamed from
copy_file_preserving.
(copy_file_preserving): New function.
* tests/test-copy-file.c (main): Test xcopy_file_preserving instead of
copy_file_preserving.
---
ChangeLog | 9 +++++++++
lib/copy-file.c | 8 +++++++-
lib/copy-file.h | 10 +++++++++-
tests/test-copy-file.c | 2 +-
4 files changed, 26 insertions(+), 3 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index b223243229..7aff116c4d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,14 @@
2024-08-24 Bruno Haible <br...@clisp.org>
+ copy-file: First step towards more consistent function names.
+ * lib/copy-file.h (xcopy_file_preserving): New declaration.
+ (copy_file_preserving): Mark deprecated.
+ * lib/copy-file.c (xcopy_file_preserving): Renamed from
+ copy_file_preserving.
+ (copy_file_preserving): New function.
+ * tests/test-copy-file.c (main): Test xcopy_file_preserving instead of
+ copy_file_preserving.
+
acl: First step towards more consistent function names.
* lib/acl.h (xset_acl): New declaration.
(set_acl): Mark deprecated.
diff --git a/lib/copy-file.c b/lib/copy-file.c
index d2588b8271..13fb0fe2e3 100644
--- a/lib/copy-file.c
+++ b/lib/copy-file.c
@@ -181,7 +181,7 @@ qcopy_file_preserving (const char *src_filename, const char *dest_filename)
}
void
-copy_file_preserving (const char *src_filename, const char *dest_filename)
+xcopy_file_preserving (const char *src_filename, const char *dest_filename)
{
switch (qcopy_file_preserving (src_filename, dest_filename))
{
@@ -219,3 +219,9 @@ copy_file_preserving (const char *src_filename, const char *dest_filename)
abort ();
}
}
+
+void
+copy_file_preserving (const char *src_filename, const char *dest_filename)
+{
+ xcopy_file_preserving (src_filename, dest_filename);
+}
diff --git a/lib/copy-file.h b/lib/copy-file.h
index 8cc0cc5ba0..cc096c49fe 100644
--- a/lib/copy-file.h
+++ b/lib/copy-file.h
@@ -16,6 +16,11 @@
along with this program. If not, see <https://www.gnu.org/licenses/>. */
+/* This file uses _GL_ATTRIBUTE_DEPRECATED. */
+#if !_GL_CONFIG_H_INCLUDED
+ #error "Please include config.h first."
+#endif
+
#ifdef __cplusplus
extern "C" {
#endif
@@ -46,7 +51,10 @@ extern int qcopy_file_preserving (const char *src_filename, const char *dest_fil
Modification times, owner, group and access permissions are preserved as
far as possible.
Exit upon failure. */
-extern void copy_file_preserving (const char *src_filename, const char *dest_filename);
+extern void xcopy_file_preserving (const char *src_filename, const char *dest_filename);
+
+/* Old name of xcopy_file_preserving. */
+_GL_ATTRIBUTE_DEPRECATED void copy_file_preserving (const char *src_filename, const char *dest_filename);
#ifdef __cplusplus
diff --git a/tests/test-copy-file.c b/tests/test-copy-file.c
index a9a811e9d4..f7ebe0dbec 100644
--- a/tests/test-copy-file.c
+++ b/tests/test-copy-file.c
@@ -40,7 +40,7 @@ main (int argc, char *argv[])
if (null_stderr)
ASSERT (qcopy_file_preserving (file1, file2) == 0);
else
- copy_file_preserving (file1, file2);
+ xcopy_file_preserving (file1, file2);
return test_exit_status;
}
--
2.34.1
